Fritz: All Fritz

home *** CD-ROM | disk | FTP | other *** search

/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / DATATURE / WAMPUM42.LZH / WAMPDOC.EXE / lha / WAMPUM / WAMPUM.DOC < prev

Wrap

Text File | 1990-08-21 | 278KB | 5,614 lines

WAMPUM tm A dBASE-Compatible, Menu-Driven Data Base Management System NOTE: Print the README.DOC file for late-breaking enhancements! It includes ALL new feature documentation for version 4. If you already are familiar with version 3.3 of WAMPUM, then you should first read the README.DOC file. If you are new to WAMPUM, then read this documentation before reading the README.DOC file. Copyright (c) Ward Mundy, 1985-1990. Ward Mundy Software, 4160 Club Drive, Atlanta, GA 30319 Second Edition. All Rights Reserved. 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 What is WAMPUM Anyway? . . . . . . . . . . . . . . . . 1 1.2 Summary of Features . . . . . . . . . . . . . . . . . 1 1.4 System Requirements . . . . . . . . . . . . . . . . . 2 1.5 Getting Started . . . . . . . . . . . . . . . . . . . 3 1.5.1 Loading the Program . . . . . . . . . . . . . . 3 1.5.1.1 Installing the Software . . . . . . . . . 3 1.5.1.2 How to Run It . . . . . . . . . . . . . . 4 1.5.2 Maneuvering on the Main Menu . . . . . . . . . . 5 1.6 Quitting WAMPUM . . . . . . . . . . . . . . . . . . . 5 1.7 Using the Cursor & Function Keys . . . . . . . . . . . 5 2 Developer Functions . . . . . . . . . . . . . . . . . . . . 7 2.1 Creating A New Application . . . . . . . . . . . . . . 7 2.1.1 Overview of Application Development Strategy . . 7 2.1.2 Create A New SubDirectory . . . . . . . . . . . . 9 2.1.3 Building a New File . . . . . . . . . . . . . . . 10 2.1.4 Selecting the New File . . . . . . . . . . . . . 12 2.1.5 Revising the Existing File Structure . . . . . . 12 2.1.6 Indexing the New File . . . . . . . . . . . . . . 13 2.1.6.1 Overview . . . . . . . . . . . . . . . . . 13 2.1.6.2 Creating New Indexes . . . . . . . . . . . 14 2.1.6.3 Selecting Indexes . . . . . . . . . . . . 15 2.1.7 Printer Configuration (.MEM files) . . . . . . . 15 2.1.7.1 Overview . . . . . . . . . . . . . . . . . 15 2.1.7.2 Selecting an Existing Printer Table . . . 17 2.1.7.3 Creating a New Printer Table . . . . . . . 17 2.1.8 Relating a Secondary File . . . . . . . . . . . . 18 2.1.9 Storing A New Configuration (Wampum.Mem) . . . . 19 2.1.10 Building Reports, Labels, and Form Letters . . 22 2.1.10.1 REPORTS . . . . . . . . . . . . . . . . . 22 2.1.10.2 LABELS . . . . . . . . . . . . . . . . . 29 2.1.10.3 FORM LETTERS . . . . . . . . . . . . . . 32 2.1.11 Building Function Key Macros (KEYS.DBF) . . . 39 2.1.12 Building Edit Checks (EDIT.DBF) . . . . . . . . 41 2.1.13 Building Data Entry Menus (MENUS.DBF) . . . . 47 2.1.14 Building an Audit Trail File (AUDIT.DBF) . . . 53 2.1.15 Preformatted Output (WAMPUM.DBF) . . . . . . . 54 2.1.15.1 Overview . . . . . . . . . . . . . . . . 54 2.1.15.2 Building the WAMPUM.DBF File . . . . . . 54 2.1.15.3 Adding To/Editing the WAMPUM File . . . . 55 2.1.16 Resetting the Developer Password . . . . . . . 56 2.1.17 Network Considerations . . . . . . . . . . . . 56 2.1.18 Making a Backup of the User Application . . . 57 2.1.19 Writing the Documentation . . . . . . . . . . . 57 2.2 ! - RUNning an External Program . . . . . . . . . . . . 58 2.3 & - Run FoxBASE+ Commands/Programs . . . . . . . . . . 58 2.4 Z - ZOOMing or RELATing a Supplemental File . . . . . 58 2.5 G - Global Replacement of Data . . . . . . . . . . . . 60 2.6 C - Copy Utilities for Importing & Exporting Data . . 61 2.7 Deleting & Undeleting Groups of Records . . . . . . . 64 i 2.8 Reserved Variables, FoxBASE & Clipper Functions . . . . 65 2.8.1 Overview . . . . . . . . . . . . . . . . . . . . 65 2.8.2 CHARACTER/STRING functions . . . . . . . . . . . 64 2.8.3 DATE functions . . . . . . . . . . . . . . . . . 66 2.8.4 DUPKEY("FIELDNAME") . . . . . . . . . . . . . . 67 2.8.5 EMPTY(fieldname) tests for empty fields . . . . 68 2.8.6 LASTTIME field in data bases . . . . . . . . . . 68 2.8.7 LASTUPDT field in data bases . . . . . . . . . . 68 2.8.8 LASTUSER field in data bases . . . . . . . . . . 68 2.9 PATH Considerations . . . . . . . . . . . . . . . . . 69 2.10 Enabling USERID's and Passwords . . . . . . . . . . . 69 2.11 WAMPUM & DOS System Errors . . . . . . . . . . . . . 70 3 End-User Functions . . . . . . . . . . . . . . . . . . . . 72 3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . 72 3.2 A - ADDing New Records . . . . . . . . . . . . . . . . 73 3.3 E - EDITing Records . . . . . . . . . . . . . . . . . . 74 3.4 D - DISPLAYing Records . . . . . . . . . . . . . . . . 76 3.5 M - MARKing a Record for Deletion . . . . . . . . . . . 77 3.6 U - UNDELETing a Record . . . . . . . . . . . . . . . . 79 3.7 P - PRINTing Records . . . . . . . . . . . . . . . . . 80 3.8 X - REBUILD/FileFix . . . . . . . . . . . . . . . . . . 81 3.9 S - SELECT Utilities . . . . . . . . . . . . . . . . . 83 3.9.1 Overview . . . . . . . . . . . . . . . . . . . . 83 3.9.2 Record Selection Criteria . . . . . . . . . . . 83 3.9.3 Listing File Contents . . . . . . . . . . . . . 89 3.9.4 Changing Current Data Entry Menu . . . . . . . . 90 3.9.5 Picking the Lead Index . . . . . . . . . . . . . 90 3.9.6 Setting Browse Mode ON . . . . . . . . . . . . . 91 3.9.7 Listing the File Structure . . . . . . . . . . . 92 3.10 R - REPORTS Generation . . . . . . . . . . . . . . . 92 3.11 L - LABELS Production . . . . . . . . . . . . . . . . 93 3.12 T - FORM LETTER Generation . . . . . . . . . . . . . 93 3.13 W - WAMPUM Preformatted Output . . . . . . . . . . . 94 3.14 Printer Selection Screen . . . . . . . . . . . . . . 95 3.14.1 Printed Output . . . . . . . . . . . . . . . . 95 3.14.2 Printer Font Selection . . . . . . . . . . . . 95 3.14.3 Output All Records . . . . . . . . . . . . . . 95 3.14.4 Output Records Marked for Deletion . . . . 95 3.15 On-Line HELP . . . . . . . . . . . . . . . . . . . . 96 3.16 Credits . . . . . . . . . . . . . . . . . . . . . . . 96 ii Ward Mundy Software - Product Offerings We have developed a number of reasonably-priced, ShareWare products which we think you will find are comparable to commercial products except in one respect: price. A brief summary of these offerings follows. See the README.DOC file for late-breaking developments! WAMPUM is a menu-driven, pop-up (TSR), dBASE-compatible data base management system. It permits even novices to develop powerful applications in minutes instead of months. Virtually every dBASE command and function is supported using easy-to-use menus. Versions are available for stand-alone PCs or NetBIOS- compatible networks. In addition, users may choose between Clipper, dBASE III+, and FoxBASE+ compatible indexes. The FoxBASE version also supports a simulated dot prompt which permits a user to enter virtually any dBASE command. Simple programs up to 500 lines also can be written and executed using the FoxBASE version. Requirements: 512K PC, DOS 2.X or higher, dual floppies or hard disk. Network version requires 640K plus DOS 3.1 or higher. See README.DOC for current features list. dLITE is a pop-up desktop file manager which permits a user to access up to 10 different dBASE-compatible data base appli- cations from within almost any text-based application. In addition to powerful file management functions, it also includes a unique PASTE function permitting users to extract data from any data base and stuff it into a word processing document, spreadsheet, or any other foreground application. Requirements: 160K or 100K with 3.2 or 4.0 EMS memory, DOS 2.1 or higher, and dual floppies or hard disk. MenuMaker is a data entry screen generator for use with WAMPUM or dLITE. The developer draws the data entry screen as it should appear to end users. Then MenuMaker writes the necessary code to support either WAMPUM or dLITE applications. WAMPUM Form Letter Editor provides an easy-to-use editor for use in developing form letter applications with FoxBASE versions. Badge-O-Magic is a name tag and badge generation program which uses dBASE III-compatible data bases to produce printshop quality nametags on any HP LaserJet II-compatible laser printer. The software includes documentation on disk and five soft fonts with point sizes ranging from 15 to 40 points. An order form to simplify ordering and registering our software is included on the next page. Please feel free to make as many copies as you need. 1 Overview 1.1 What is WAMPUM Anyway? Ward's Automated Menu Package Using Microcomputers (WAMPUM) is a full-featured, menu-driven implementation of the dBASE III programming language. WAMPUM can wear two hats: it is both an application development tool and an end-user data base management system. The software is a copyrighted work owned by Ward Mundy which is licensed for use under certain terms and conditions which are displayed when you run or terminate the running of the program. The ShareWare versions may be used for up to 90 days to determine whether the software meets your data base needs. Then you may either pay the applicable license fee or discontinue using the program. The ShareWare version only may be redistributed so long as it is distributed with all the files exactly as received. If you purchased WAMPUM from a ShareWare distributor, the copying fee may not exceed $10 U.S. If this was not the case or if you received a damaged version of the software, please do yourself and your friends a favor. Let us know about it, and don't use the damaged version! Special thanks to Nantucket, Inc., the developer of Clipper, the premier dBASE III compiler. Without Clipper, there would be no WAMPUM. Clipper's flexibility and many enhancements over Ashton-Tate's dBASE interpreters made development of WAMPUM a true labor of love. We also express our sincere appreciation to Nantucket for authorizing the distribution of their REPORT.EXE and LABEL.EXE programs to end-users without additional charge. These two programs simulate the dBASE III commands of Create Report and Create Label and make WAMPUM a complete stand-alone application development system without reliance upon any dBASE interpreter. One version of WAMPUM now relies upon the FoxBASE+ run-time interpreter which is included with the WAMPUM software. This version includes a report writer and label generator without reliance upon any external program. This version also permits the developer to write unnested, FoxBASE-compatible programs up to 500 lines and execute them from within WAMPUM. We do NOT provide technical support to those wishing to write their OWN FoxBASE-compatible programs! 1.2 Summary of Features WAMPUM provides much of the functionality of the dBASE III Plus programming language through a simple menu interface. Various versions of WAMPUM now support floppy- only systems, network-based systems, and all existing dBASE index dialects: Clipper, dBASE III Plus, and FoxBASE+. dBASE IV index support will be available by mid-1989. The major features included in WAMPUM are outlined below. 1 * Creation and use of dBASE III Plus-compatible data bases * Multi-user network support using any dBASE III file * Field types include: Char, Numeric, Date, Logical, Memo * Creation and use of up to 7 B-Tree Indexes per .DBF file * Add, Edit, Delete, & Undelete Records in any .DBF file * Display, List and Print Records from any .DBF file * 10 Data Entry Screen Formats tailored to any application * Automatic, semi-automatic, and custom data entry screens * Create and use dBASE III-compatible reports & labels * Create and use WAMPUM "mail merge" form letter files * Relation of second data base by key for any output * Full-featured copy utilities to import & export any data * Creation of printer templates to support up to 10 fonts * Library of preformatted output forms with sort & select * Library of edit-checks tailored to any .DBF file system * Library of macros tailored to any WAMPUM application * Calculated fields using standard dBASE expressions * Automated Selection Assist for complex Boolean searches * Boolean search of MEMO field in versions except FoxBASE * Audit Trail / Transaction Logging for multi-user tasks * NetBIOS-compatible record & file locking network support * Passwords and custom user configurations for networks * Global search & replace of 10 data elements in one pass * Retrieval of 9 custom applications with a single keystroke * Date formats to accommodate international date formats * 'Dot prompt' to run custom programs in FoxBASE version * Support for dBASE screen format files in FoxBASE version 1.4 System Requirements WAMPUM may be used on IBM PC-compatible computers running DOS 2.1 or higher. For multi-user network applications, DOS 3.1 or higher is required on every computer as well as an IBM NetBIOS-compatible network. For performance reasons, an 80286 or 80386 processor and a hard disk are desirable. Minimum memory requirement is 420K above and beyond the memory requirements of DOS and any memory- resident programs in use. Minimum memory is 420K (with DOS 3.1) to link to REPORT and LABEL programs from within WAMPUM. Without much in the way of memory-resident software, WAMPUM typically needs 512K to operate satisfactorily after loading DOS. WAMPUM will run on either a monochrome or color display. Because WAMPUM creates a number of work files from time to time, and because WAMPUM typically works with numerous files open at the same time, you will need to make sure that when your computer is started, a file named CONFIG.SYS exists in the root directory of the boot disk. This file must contain the following entries with the minimum values shown: FILES=20 BUFFERS=24 2 1.5 Getting Started 1.5.1 Loading the Program 1.5.1.1 Installing the Software WAMPUM is distributed on one or more diskettes in an archived (compressed) format to conserve disk space. Prior to installing the software, you must create a directory on your disk to house WAMPUM. The directory must be the first directory in your DOS PATH for performance reasons. This also will assure that WAMPUM can be run from any subdirectory on your system. If you are not familiar with the PATH command, consult your DOS manual for more details. Simply stated, the PATH command tells DOS which directories (other than the current one) should be searched whenever you ask the computer to run a program. Exit to the DOS prompt and type PATH and press <ENTER>. For ease of presentation, we will discontinue repeating press <ENTER> after each command. Unless instructed otherwise, type a command and press <ENTER>. If DOS reports "no path," then you must create one before installing or running WAMPUM. First, create a new directory (file drawer) by typing MD \WAMPUM. Then, create a path by typing PATH=C:\WAMPUM. If your default drive is not C:, then substitute the appropriate drive letter for C: above. NOTE: The PATH command is only preserved until you turn your computer off. You must reenter the PATH command each time you turn your system on before running WAMPUM unless the PATH command is included in your AUTOEXEC.BAT startup file. Consult your DOS manual for additional guidance. If DOS reports that a path exists, then you have two choices. Either install WAMPUM into the first existing directory in the DOS PATH or follow the steps above and add C:\WAMPUM as the first directory in the DOS path. WAMPUM cannot be run as distributed in its archived form. It first must be unarchived. Insert the distribution diskette in Drive A of your computer and type A:INSTALL. You then will be instructed how to proceed. For the Clipper and dBASE-compatible index versions, WAMPUM.EXE, REPORT.EXE, LABEL.EXE, and printer configuration files with a .MEM file extension will be copied into the directory you have identified as the first directory in your DOS PATH. Do not rename these files. 3 1.5.1.2 How to Run It WAMPUM is designed to support two, very different audiences. The first group is end-users, and the second is application developers. This design is implemented by providing different menu options for the two groups. The end- user menu options are designed to let end-users do the normal things that are done with a database: adding, editing, and deleting records; running reports and labels; selecting the primary index for input and output of data; and entering record selection criteria to narrow down which records are produced in listings and reports. Provision is also made to allow end-users to rebuild a damaged data base or index typically occasioned by a power failure. The end-user mode is initiated by typing WAMPUM and pressing the <ENTER> key at the DOS prompt. This is true for all versions. WAMPUM's developer mode contains all of the options outlined above plus a number of additional options designed to allow a person to develop a data base application for others to use. You do NOT have to be a programmer to become a good WAMPUM developer! The developer's mode allows the creation of new data files and indexes as well as reports, labels, and printer formats. It also provides access to the data files used to develop edit checks, data entry menus, keyboard macros, preformatted output, and form letters. Finally it allows for customization of applications through the storing of a configuration identifying the files, indexes, printer, and name of each application. The developer mode is initiated by typing WAMPUM VOODOO at the DOS prompt. If you are using WAMPUM on a compatible such as an older COMPAQ which makes DOS think it has a color card even when using a monochrome display, then you may want to force WAMPUM into monochrome mode by starting it with WAMPUM MONO or WAMPUM VOODOO MONO. In the FoxBASE+ version, monochrome mode can be specified in the * - Config Update option. Except in the FoxBASE+ versions, WAMPUM uses an external Report Writer (Report.Exe) and a Label Generator (Label.Exe) to create report and label templates. Depending upon the amount of memory in your machine, these programs may or may not be able to run from within the WAMPUM program itself. This User's Guide explains the procedure for running REPORT and LABEL from within WAMPUM. If you lack the necessary memory to do this, you may run the report writer from the DOS prompt by typing REPORT filename where filename is the name of the report template you wish to create or edit. You may 4 run the label generator from the DOS prompt by typing LABEL filename where filename is the name of the label template you wish to create or edit. 1.5.2 Maneuvering on the Main Menu Once you have started WAMPUM by executing one of the commands outlined above, you will see the WAMPUM logo and then the Main System Menu. Note that just below the menu is a one-line sentence of HELP regarding the highlighted option. You move between the options with the UP and DOWN cursor keys. The HOME key will take you to the first option on the menu, and the END key will move you to the last option. Execute a choice on the Main System Menu by pressing the <ENTER> key when the choice desired is highlighted or simply type the LETTER corresponding to the choice you wish to run. Using the first letter method, you do not have to press <ENTER>. Context-sensitive HELP on most features is accessed by pressing the F1 function key on any screen. 1.6 Quitting WAMPUM The <ESC> key is pressed to exit from WAMPUM to DOS from the Main System Menu. Then answer the prompt. 1.7 Using the Cursor & Function Keys A number of keys have special functions within the WAMPUM system. Oftentimes, these keys are not the same as what you may have used in previous dBASE applications. Please scan through the summaries below before you attempt to either use or build a WAMPUM application. Throughout this manual, you will see references to multiple key combinations such as CTRL-W or ALT-F10. Whenever you see a hyphenated key combination such as these, it means hold down the first key, then tap the second key, then release both keys. For example, CTRL-W means hold down the CTRL key, then tap the W key (case does not matter), then release both keys. We use the word "TAP" advisedly. Most PC's have a "keyboard buffer" which remembers keystrokes which may not yet have been displayed. Every key on the PC acts like a repeating key on a selectric typewriter. Thus, TAP means touch and release promptly! <ESC> is the all-purpose key which is used to get you out of trouble. From ANY screen, you can always press the ESCape key to exit without preserving what you already were 5 doing. From the Main Menu, pressing <ESC> will terminate WAMPUM and return you to the DOS prompt. Ctrl-W is WAMPUM's SAVE key. Pressing CTRL-W typically tells the computer to SAVE what is displayed on the screen and move on to the next step. If you are a previous dBASE III user, then CTRL-W is equivalent to dBASE III's CTRL-End key. In FoxBASE+ versions, CTRL-End also works. Ctrl-Home moves the user to the first field on a data entry screen in all versions except FoxBASE+. Ctrl-End moves the user to the last field on a data entry screen except in the FoxBASE+ versions. <Enter> or <Down> Cursor completes an entry in a field and moves the user to the next field, if any, on the screen. <Up> Cursor moves the user to the previous field, if any, on the screen. <PgDn> signifies that data entry for this screen of data has been completed and that the user wishes to SAVE the data and continue. <PgUp> signifies that data entry for this screen of data has been completed and that the user wishes to SAVE the data and continue backwards through the data base (except when ADDing new records to the data base). Ctrl-<Left> Cursor moves the cursor to the beginning of the current data entry field. Ctrl-<Right> Cursor moves the cursor to the end of the current data entry field. Ctrl-Y deletes the contents of the current field from the cursor position to the end of the field. <Ins> toggles the computer between insert mode and strike-over mode. The word <INSERT> appears at the top of the screen when INSERT mode is active. <Del> deletes the character currently under the cursor. F1 function key is the all-purpose HELP key. It retrieves a screenload of helpful hints which are keyed to your position in the WAMPUM system. F2-F10 function keys are macros tailorable by the developer to hold any character string desired. The same is true for SHIFT, ALT, and CONTROL key combinations except Fox. 6 2 Developer Functions 2.1 Creating A New Application 2.1.1 Overview of Application Development Strategy As with any application development, the best advice in starting a new project is turn off the computer and scratch your head for a while to figure out what you want to do. What data input is needed to get the output desired? Once you know what you want, then some familiarity with WAMPUM's structure and the basics of dBASE will help. WAMPUM is designed to be stored in a directory from which it can be run regardless of the active default directory on your hard disk. The cardinal rule in using WAMPUM is a simple one: separate applications must be created in separate sub- directories which are NOT in your DOS PATH. There are two reasons for this. First, WAMPUM creates a number of supporting files for each application. If you create more than one application in a given subdirectory then these supporting files will not be available for use in both applications. Second, because WAMPUM accesses files on the disk using the same PATH command that DOS uses, if you build an application in a directory which is part of the PATH, then WAMPUM's supporting files may unintentionally spill over into other WAMPUM applications as you begin building them. Each WAMPUM application typically will include a main file, perhaps a related file, several indexes, and numerous reports, labels, and forms. In addition, each time you run WAMPUM in a new directory, it automatically builds some supporting files for that application. These include EDIT.DBF (which is used to store the edit checks for a particular application), KEYS.DBF (which is used to store any keyboard macros for a particular application), MENUS.DBF (which is used to store up to 9 data entry screen formats) and, if requested, WAMPUM.DBF (which is used to build a library of preformatted reports, labels, and form letters which can be run without users having to master Boolean logic and sorting rules). Finally, WAMPUM stores a configuration for each application in a file named WAMPUM.MEM. For the reasons stressed above, you should not run WAMPUM in a directory which is part of the DOS PATH since it would create these supplemental files. They then would inadvertently be accessed whenever you tried to use other applications on your disk! For those unfamiliar with dBASE and its spin-offs, a quick thumbnail sketch of its design may help you get 7 started. dBASE stores data base information in sequential files with a file extension of .DBF. The first part of each .DBF file defines the "structure" of the data base, i.e. the unique names of the different pieces of information (fields) to be stored as well as each field's type and length. As you add new data to the file (records), it is tacked onto the end of the existing file. Thus, a file consisting of three records would, in fact, have a file structure followed by records 1, 2, and 3 in sequential order. For small data bases, sequential data bases work well; however, it means that a search for any given record must proceed by examining each record in the data base until the proper record is found. Since WAMPUM supports files with literally millions records, the time for sequential searching obviously would become unbearable quickly. dBASE indexes solve this dilemma by providing separate files which in reality are nothing more than alphabetized lists telling dBASE how to find a given "key" within a large data base quickly. The beauty of indexes is that, once created, they are constantly updated as the information in the main data base changes. An index file may contain keys for just one field in the data base (such as zip code) or it may contain very sophisticated keys for a group of fields based upon some developer-specified algorithm. For example, in indexing the names of college alumni, one might wish to index males and unmarried females by zip code, then last name, and then first name. For married females, the index should be by zip code, maiden name, and then first name. This would enable quick retrieval of alumni by the names actually used while in college. In data processing terms, an index performs the same function as a sort except that an index is always sorted. In other words, it provides an instant sort. And, you can have up to seven different indexes in use with every individual data base. To change the sort order, all one does is change the lead (first) index. But, all seven indexes remain sorted and current. This saves an enormous amount of time when the time comes to run a report since no intermediate sorting step is ever required. All one does is choose the lead index which instantly "sorts" the report in lead index order. dBASE reports (.FRM files) and labels (.LBL files) are actually formatting templates which tell the system how to display information from a given data base. In short, you "pour" your data base through the template to get a formatted report. Unlike some data base systems, no data is actually stored in the dBASE report. And report or label templates do not tell the system which records to actually print or in what order. A template only specifies which fields to print 8 and what headings to put on the paper. Choosing the order of records to print is done by selecting the lead index. Picking records for a report is done using a filter which is nothing more than record selection using Boolean logic. WAMPUM eases the pain of this process by providing a menu- driven, "Plain English" assistant to guide you through the record selection process. What follows in the subsequent sections of this chapter is a step-by-step tutorial for building a sample WAMPUM application. Before you do anything else, do yourself a favor and complete this tutorial. It will take less than two hours! In order to simplify the presentation, let's create a sample application which is as generic as possible. We will assume that the application is based upon the data base outlined below. The structure of the primary file follows: FIELD NAME TYPE LENGTH DEC LASTNAME C 20 0 FIRSTMI C 20 0 ADDRESS C 40 0 CITY C 20 0 STATE C 2 0 ZIP C 10 0 PURCHAMT N 7 2 PURCHDT D 8 0 MARRIED L 1 0 COMMENTS M 10 0 2.1.2 Create A New SubDirectory The first step in building a new WAMPUM application is to create a new subdirectory on the disk to house the information. You must be at the DOS prompt to perform these steps. We recommend you name the subdirectory using a single word of up to 8 characters in length with no embedded spaces or punctuation. To keep things simple, let's name it CUSTOMER here. If you want to follow along, type the following commands. PROMPT $P$G MD \CUSTOMER CD \CUSTOMER 9 The commands above (1) change the DOS prompt to assure that you'll know the subdirectory in which you are working, (2) make a new directory named "CUSTOMER" below the root directory, and (3) move you to the new CUSTOMER directory. If you are working on the C: drive, the prompt on your screen after issuing the above commands should be C:\CUSTOMER>. You now are ready to start up WAMPUM. Since you are building a new application, you will want to use Developer Mode. This means you need to include the developer password as shown below. Unless you need to force WAMPUM into mono mode, type WAMPUM VOODOO. If you have a Compaq or some other clone that reports a color card when you are using a monochrome display, then type: WAMPUM VOODOO MONO. For users of the FoxBASE+ versions, type WAMPUM. 2.1.3 Building a New File The first piece of the new application to build is the main data file. This may contain up to 400 fields depending upon the amount of free memory in your computer. Be aware that you will forfeit dBASE III Plus compatibility when you create more than 128 fields. Select the B - Build New File option from the Main System Menu by typing a B or highlight the option and press <ENTER>. You then will be prompted to enter a file name for your new data base file. The file name must comply with DOS requirements for file names, i.e. up to 8 characters, no spaces, and preferably no punctuation. Think of a file name that bears some relationship to the application. It makes things easier. For our sample, let's use CUSTOMER. Type in the file name and press <ENTER>. Note that you do NOT enter the file extension which WAMPUM assigns as .DBF. You then will be prompted to enter four pieces of information for each new field in your data base: a field name, a field type, a field length, and field decimals (for numeric fields only). In determining the order of the fields in the data base being created, keep in mind that BROWSE mode, which is discussed under the Select Utilities option, displays a single line of fields for 20 records at a time. If your users will be using BROWSE mode, then you should select the most important fields in the data base as the first fields in the file. This will assure that they are displayed when the 10 user sets BROWSE mode ON. The actual number of fields which will fit on a single line of the screen is determined by two factors: (1) the length of the field names used, and (2) the maximum length of the field data. Adding the greater of these lengths for each field plus a space between each field, WAMPUM will display as many fields as will fit within 79 characters in BROWSE mode. The first character position of the line is reserved to display whether a record has been marked DELETED. Field names should bear some resemblance to the piece of data which will be stored in the field. dBASE III supports 10 character field names, and WAMPUM can use them, too. However, applications are much more straight-forward if field names are limited to 8 characters or less since this length matches the DOS filename length restriction. Field names must begin with a letter of the alphabet. Subsequent characters in the field names may be characters, numbers, or the underscore character. Field types and lengths supported by WAMPUM include: Field Type Abbrev Min. Max. Comments Len. Len. Character C 1 254 Any text string Numeric N 1 15 Numeric for math Date D 8 8 Any date info Logical L 1 1 True/False info Memo M 10 10 Free-form WP text Field decimals will always be 0 except for numeric fields in which you want to use real numbers, i.e. those with decimals. Remember that with such fields, the TOTAL length is the maximum number of integer positions, plus 1 for the decimal, plus the number of decimal positions. Thus, if the largest value to be entered in a numeric field is 9999.99, the field length is 7 and decimals is 2. Enter the information for the fields outlined in our sample data base. After entering all of the fields, a new blank record will appear. Press the <ESC>ape key to indicate that you are finished except in the FoxBASE+ versions. In the FoxBASE+ versions, press CTRL-End. 11 2.1.4 Selecting the New File Once the data base structure has been created, you are ready to tell WAMPUM which file you will be working with. From the Main System Menu select the F - File Select option to place the file in use. In all versions of WAMPUM, a window displaying all files in the default directory will appear. Highlight the file desired using the cursor keys, and press <ENTER>. The bottom of the Main System Menu now should show the file in use with a notation: FILE: CUSTOMER. 2.1.5 Revising the Existing File Structure Beginning with version 3.1, WAMPUM provides a simple facility to revise the structure of an existing data base. This often becomes necessary when you design an initial data base without spending some time thinking about what you need. To revise the structure of an existing data base, you first must select that file for use with the F - File Select option. Once the file is in use, select the B - Build New File. The prompt will advise you to insert an asterisk (*) for the file name if you desire to revise the existing data base structure. Type an asterisk and press <ENTER>. WAMPUM will ask whether you really want to revise the structure of the data base. Type Y. For all versions except FoxBASE+, WAMPUM will display up to two columns of fields from your data base. For each field, you may change the field name, field type, field length, and field decimals. You also may delete a field from the structure by marking the DELETE? option True. If you change the name or field type of an existing field, ALL DATA which exists in that field throughout your data base will be destroyed! Never change a field type without also changing the field name or an error will result. If you need to change a field type only, you will need to use the COPY UTILITIES option to copy the data to an SDF file, then copy it back into a new data base structure. If there are more than 40 fields in your data base structure, you can move through them using the <PgDn> and <PgUp> keys. Once you have made all the changes to existing fields desired, press the <ESC> key to proceed or CTRL-End in FoxBASE+. WAMPUM then will ask whether you wish to ADD new fields to the existing data base. If you need additional fields, type Y and you will be prompted for a field name, type, length, and decimals entry for each new field. You also can 12 use <PgUp> and <PgDn> to move through the existing fields. You may also press <CTRL-N> to insert a new field at any place in the file structure. <CTRL-U> will delete or undelete any existing field. Once you have added all new fields desired, press <ESC> to proceed except Fox+. Once the data base has been revised, always reindex using the X - Rebuild/FileFix option. If you are using edit checks, data entry menus, or keyboard macros which were keyed to the old file structure, make certain that these are revised to reflect the new data base structure before adding or editing data in the data base. This is explained in more detail below. 2.1.6 Indexing the New File 2.1.6.1 Overview WAMPUM indexes serve two functions in run-time appli- cations. First, they provide a quick means of retrieving records for edit, display, or printing. Typical retrieval times even with large data bases are less than one second. Indexes also serve as the sorting tool for all output: reports, labels, and form letters. Thus, in building a new application, you need to take these considerations into account. You will need indexes to retrieve your data quickly for updating. And you may need other indexes to assure that reports, labels, and form letters are produced in the proper sorted order. As indicated previously, the primary advantage in using indexes rather than a sort for output is that no physical sorting of the data base ever takes place since the indexes are constantly updated as new records are added and old ones are modified. This saves an enormous amount of time in producing reports. WAMPUM supports up to SEVEN indexes for any application. It should be noted that while these indexes function much like the indexes in dBASE III Plus, they are not necessarily compatible. dBASE III Plus, FoxBASE+, and Clipper all provide functionally equivalent indexes; however, each vendor thinks their product's indexing algorithm is better. Thus, if you are moving dBASE III Plus data bases over to use with WAMPUM, the data base, reports, and labels are compatible, but the indexes may need to be rebuilt unless you have 13 purchased WAMPUM with dBASE-compatible indexes. In any event, indexes can be rebuilt easily. Select the I - Index Select/Create option from the Main System Menu. This option provides a developer with the means to create new indexes and to use existing ones. Both avenues are addressed in the following sections of this Guide. 2.1.6.2 Creating New Indexes New indexes can be created in one of two ways depending upon the type of index desired and the version of WAMPUM you selected. WAMPUM can create an index of any character, numeric, or date field as it exists in the data base. In our sample data base, let's assume we want a zip code index. In addition, you can create a special index made up of a com- bination of fields in the data base using dBASE string mani- pulation functions. For example, in our sample data base, we might want a single index which sorted the data base on last name and then first name within last name. The simple index is a single field index. In the floppy version of WAMPUM, choosing the I-Index Select/Create option will display a window with several options. Highlight the Create New Index File option and press <ENTER>. Then highlight the field you want to index and press <ENTER>. In our example, you probably would want a simple index on the ZIP field. Create the index following the steps outlined above. In some circumstances, a more complex index may be desired. If you know what you are doing (i.e. you really are a dBASE III programmer), you can build any type of index to achieve any type of sorting desired. In floppy versions of WAMPUM, choose the Create New Index File option, then press <End> to move to the option labeled ** Special Index** and press <ENTER>. In all versions, you then will be prompted to name the new index file and then to enter the index expression. This expression can be ANY legal dBASE III string expression. Note that index expressions always must equate to a fixed length. Thus, if spaces are trimmed off the end of a field, they must be added as real spaces at the end to assure a fixed length index. An example may help clear the fog. For example, if we wanted to index on last name then comma space then first name, enter FULLNAME for the name of the index file. Then for the index expression, type: 14 SUBSTR(TRIM(Lastname) +", "+ FirstMi + SPACE(20),1,42) The SPACE(20) expression assures that every full name index entry will be at least 42 characters long regardless of the actual length of the trimmed LASTNAME. SUBSTR() is a dBASE function which extracts a substring from a string. Its syntax is SUBSTR(char_expr,starting position,string length). Finally, note you can only concatenate strings if each evaluates to a character expression. This is satisfied if a field is a Character type, or if text is surrounded in quotes, or if a dBASE function evaluates to a character expression. 2.1.6.3 Selecting Indexes Once you have built new indexes, they automatically are selected for use in the same order they were built. You can change both the LEAD INDEX and the active indexes at any time by picking the I - Index select/create option. In the FoxBASE+ versions of WAMPUM, enter the number of the lead index or the names of desired indexes. In other versions of WAMPUM, choose Select Indexes to Use or Pick Lead Index, and highlight your desired choices. You also may press <ALT-I> from the Main System Menu to change the lead index in all WAMPUM versions except FoxBASE+. One caution is in order. Remember that indexes are only UPDATED with ADD or EDIT if those indexes are in use at the time the file is changed! You can ascertain which indexes are in use by looking at the INDX listing which appears below the Main System Menu. If you built the indexes recommended in the last section, the last line of your screen should read as follows: FILE: CUSTOMER INDX: ZIP,FULLNAME 2.1.7 Printer Configuration (.MEM files) 2.1.7.1 Overview In order to create high-quality output in reports, labels, and form letters, you will need to configure an application for a specific printer. WAMPUM is packaged with several printer configuration tables which already have been built to support a number of popular printers. If you're a lucky person, your work has already been done. If not, read the section on constructing a new printer table below. 15 WAMPUM is designed to allow a developer to imbed printer codes in reports, labels, and form letters to control the actual printing of text. In addition, the end-user can specify the starting printer font to be used to output any report, label, or form letter. Finally, WAMPUM preformatted output includes the option of specifying the initialization printer string. What is a WAMPUM printer table? It is a standard dBASE III memory variable file (.MEM file extension) with special codes that tell your printer to print in a certain mode. The following field names are reserved by WAMPUM and should not be used as field names in your data bases. These fields can be used in creating report forms, labels, and form letters to vary the type styles within those output documents. This may include turning underscore on and off. FONTINIT FONT1 FONT4 FONT7 FONTRESET FONT2 FONT5 FONT8 FONT0 FONT3 FONT6 FONT9 Note that the FONTINIT string always gets sent to the printer before anything is printed. The FONTRESET string always gets sent after anything is printed. If these fields are empty, then obviously nothing gets sent. The default font for all output is FONT0. This always gets sent after the FONTINIT sequence unless you specify some other number when the output is generated. Listed below is the definition logic used to develop the font codes for the HP LaserJet printers. It is similar to what was used for the Epson printers, except all output is in portrait mode with Epson dot matrix printers. In general terms, FONT9 is reserved for very small print to accommodate reports of 132 columns. FONT8 is reserved to accommodate reports from 81 to 110 columns wide. FONT7 is used with the lasers to get mailing labels to line up. FONT0 10 pitch Courier, portrait mode FONT1 10 pitch standard, portrait mode FONT2 10 pitch bold, portrait mode FONT3 10 pitch italics, portrait mode FONT4 Proportional, big bold, portrait mode FONT5 Proportional, baby print, portrait mode FONT6 Standard, baby print, portrait mode FONT7 10 pitch with codes suitable for LABELS FONT8 10 pitch, standard, landscape mode FONT9 Standard, baby print, landscape mode 16 Obviously, use of these font codes can be adjusted as your application demands. There may be instances in which you need underscoring. This can be accomplished using one font to turn on automatic underscore and another to turn it off if your printer supports it. 2.1.7.2 Selecting an Existing Printer Table To select an existing printer table for use, choose the option labeled # - PRINTER Config on the Main System Menu. A listing of all .MEM files in the current directory will be displayed. In floppy versions, enter the name of the printer table you wish to use without the .MEM file extension. In other versions, highlight the desired font file and press <ENTER>. Note that you may use a table which is stored in another directory so long as that directory is part of DOS's PATH command if you know the file's name. Once you have selected a printer, the Main System Menu will reappear and the last line on the screen should now show the printer and FONT in use. Assuming you selected the HPLASERA font, the last line of your screen should look like this: File: Customer Indx: Zip,FullName Prt: HpLaserA/0 2.1.7.3 Creating a New Printer Table If there is no printer table already available for your printer, then you will need to build one. It's easy! First, select the # - PRINTER config option on the Main Menu. In the floppy versions, when WAMPUM prompts for the name of the printer table to use, type an asterisk (*) and press <ENTER>. In other versions, highlight the Create New File option and press <ENTER>. After entering a file name for your new printer template, you then will get a data entry screen in which to type the special codes for your printer. Your printer manual is necessary to find the codes. First, decide what you want each of the printer fonts to do. You also must determine what sort of initialization sequence, if any, you want to send whenever anything is printed. And, you will want to decide whether to reset your printer after the printing is completed. Almost every printer has some code sequence which resets the printer to its default settings just as if the printer had been switched off and on. This is a good idea! It always assures that 17 your printer is configured in a standard way for the next job. It's an equally good idea to execute this reset as part of the printer initialization sequence for the same reason. Most printer codes start with an <ESC>ape code which has the ASCII value of 27. In a lot of printer manuals, it is referred to as CHR$(27) which is the way <ESC> is written in BASIC. Any time you see a code written as above which cannot be typed using the standard typewriter keyboard, you can enter it in WAMPUM just as you would in LOTUS 1-2-3 or Symphony, i.e. \027 (a backslash followed by a three-digit number representing the ASCII code of the character desired: zero, two, seven). For example, if your printer manual says that ESCAPE E or CHR$(27)+E is the escape sequence to reset your printer, then enter the following: \027E. Particularly with laser printers, it may be desirable in some situations to force some carriage returns at the beginning of a job. This is especially true to line up mailing labels. To accommodate this, WAMPUM permits the developer to insert carriage return codes in the font setups using the tilde (~). One tilde means one return. Two tildes means two returns, etc. Make certain that ALL tildes follow the complete escape sequence you desire to generate for each font code since characters following tildes are ignored. Do NOT use tildes in the FONTINIT, FONTRESET, FONT0, or FONT2 codes since these have special uses in WAMPUM. Use this process to build the printer table for your printer, and you're all set. Press the <PgDn> key when you have entered all of the codes desired. Note that you also can edit an existing printer table by entering an * as if you were creating a new printer table. When WAMPUM prompts for the name of the new printer table, simply enter the name of the old table. When the data entry screen appears, you will see that codes such as \027 have been converted by WAMPUM into the actual ASCII character. In the case of the <ESC> code, this is an arrow pointing left. These codes can be edited as desired. A final word of warning. Do NOT press the <ESC> key to enter an escape code! This key allows you to ABORT updating a printer table. To enter an escape code as part of a printer string, you must type \027. 2.1.8 Relating a Secondary File For purposes of report, label, and form letter output, you may relate or link a secondary data base to an identical field in the primary data base if two conditions are met. 18 (1) The secondary data base must be in the default directory or in the path specified by the DOS PATH. (2) The secondary data base must be indexed on a field identical in size, type, and field name with a field in the primary data base. Note that the matching field in the primary data base need not be indexed. Whenever a report, label, or form letter is run while a related file and index are set, the developer may access data in any of the fields of the matching related file record by specifying the field names with the following syntax: ALIAS->fieldname where ALIAS is the name of the related file and FIELDNAME is the name of the field to be output from the related file. A secondary file may be related in one of two ways. The first is to select the Z - Zoom/Relate File option on the Main System Menu and enter the name of the file and index to be related. This relation stays in effect until changed provided you save it as part of the configuration. Once a file has been related successfully, the file name display on the last line of the Main System Menu screen should look like the following: FILE: ACCOUNTS/R Any reports, labels, or form letters produced after relating the secondary file may access the fields in the related file also. The second method of relating a file and index is as part of developing the WAMPUM PreFormatted Output file. This is discussed in a subsequent section of the User's Guide. It provides additional flexibility since it permits the developer to relate different secondary files and indexes to different reports, labels, and form letters. WAMPUM Preformatted Output does not rely upon the relation established using the Z - Zoom/Relate File option. 2.1.9 Storing A New Configuration (Wampum.Mem) The configuration of a given application is stored in a configuration file called WAMPUM.MEM. You can change the default configuration by picking the configuration option from the Main System Menu. Select * - CONFIG Update. For each application you build, you may store certain information as a configuration: 19 (1) HEADING is the name to be assigned to a given application. It appears above the Main Menu and also appears at the top of reports. Press CTRL-Y to clear the default WAMPUM masthead. (2) MAIN FILE DRIVE, RELATED DRIVE and DEFAULT DIRECTORY. Use these if your data bases are not stored in the default directory. If you will be accessing multiple applications with a single keystroke, make certain to specify only a DEFAULT drive for every application. This should be the DRIVE:\PATH name where each application is stored. (3) MENU #'s. This is a listing of all menu choices available to end users. The choices on the Main System Menu are numbered 1 to 21 beginning in the upper left corner, reading down, then right. Make certain that at least one space precedes each available menu number. Delete numbers that correspond to menu choices you wish to disable. (4) FORM LETTER MARGINS. Specify the default left and right margins for form letters. (5) PRINTER OUTPUT. This may be the name of a network printer device for those using networks, or it may be a legal DOS file name if you wish to redirect printer output to a file. (6) AUDIT TRAIL FILE. Marking this option True enables WAMPUM's audit trail. (7) CONFIRM FIELD ENTRIES. Marking this option True means a user must press <ENTER> to confirm each field entry before the cursor will move to the next field. (8) NETWORK. Marking this option True enables automatic record locking for those who have purchased network versions of WAMPUM. Otherwise, WAMPUM imposes a file lock when any data base is accessed. (9) COUNTRY. The country code number entered determines the formatting of dates with WAMPUM. The following formats are supported: 1 American MO/DA/YR 2 ANSI YR.MO.DA 3 British/French DA/MO/YR 4 Italian DA-MO-YR 20 (10) MEMO WIDTH. In FoxBASE+ versions, you may specify the default MEMO field width for output in lists and reports. The default is 50. (11) UPDATE MEMORY VARIABLES. In FoxBASE+ versions, you may specify up to 9 memory variables by marking this field True. These variables can be used in reports, labels, and form letters as well as in edit checking routines that require a simple table of values. In addition to the above, saving a WAMPUM configuration also saves the following information: (1) Name of File and Related File In Use (2) Name of Indexes In Use (3) Name of Default Printer Template (4) Range of Available Data Entry Menus (5) BROWSE Mode Default Setting (On or Off) Once an application is configured, then WAMPUM remembers the above settings the next time WAMPUM is run whether in Developer or End-User mode. This permits a developer to completely customize a WAMPUM application and then turn it over to end-users without the end-user having to master all of the concepts involved in building an application from the ground up. Beginning with version 3.2, WAMPUM allows nine different configurations to be saved using file names of WAMPUM.1 through WAMPUM.9. To create these files, simply copy WAMPUM.MEM to the new file name. Then run WAMPUM again, save a new configuration, and copy it to one of the other reserved file names. These nine configurations can be retrieved with one or two keystrokes. Press ALT-1 through ALT-9, or press ALT-0 to retrieve WAMPUM.MEM defaults. Make certain that all config files WAMPUM.1 through WAMPUM.9 are copied to every directory in which you wish to access the other configurations. 21 2.1.10 Building Reports, Labels, and Form Letters 2.1.10.1 REPORTS 2.1.10.1.1 Overview Except for FoxBASE+ versions, WAMPUM Reports are designed using the Clipper REPORT Generator, which Nantucket generously has allowed us to distribute without charge. Before you can create new report forms or revise old ones, you need to make sure the program REPORT.EXE is located in a directory supported by your DOS PATH command. This will assure that WAMPUM can access the report generator whenever you want to design or redesign a report form. Users of FoxBASE+ versions can ignore this. As indicated previously, WAMPUM requires a minimum of 420K memory to access the report writer from within WAMPUM with DOS 3.1. If you are short on memory, you can run REPORT.EXE from the DOS prompt by typing REPORT filename where filename is the name of the report you wish to create or revise. Note: Some versions of WAMPUM later than 3.1 may provide the flexibility to create reports without reliance upon REPORT.EXE. Consult the README.DOC file for the latest information. Before designing a report, you will always want to print out a listing of the file structure with which you will be working. Pick the S - Select Utilities option and specify T or Y for the List File Structure option. Then type Y when asked whether to print the structure listing. Both the Clipper and FoxBASE+ Report Generators are quite similar to dBASE III's report writer which is accessed in dBASE with the command CREATE REPORT filename or MODIFY REPORT filename. Thus, anyone who is generally familiar with the dBASE III method of designing report forms will have no problem doing the same with WAMPUM. A report form is a file which contains a template telling WAMPUM which pieces of information you want to extract from a data base. Note that we said "which pieces of information" meaning which fields rather than which records. This is an important distinction since neither WAMPUM reports nor dBASE reports control which records print on a report. That is controlled with record selection using the S- Select Utilities option in WAMPUM. You might more accurately refer to report forms as a formatting mold through which you "pour" information from a data base. 22 All WAMPUM reports must have a DOS-standard file name with no file extension. As is true with dBASE, WAMPUM supplies the file extension of .FRM with reports. The R - REPORTS Menu option on the WAMPUM Main System Menu provides three capabilities to the user. (1) You can run any existing report form whether created with any dBASE III Plus-compatible report writer. (2) You can create new report forms using the Clipper Report Generator or the FoxBASE+ Report Generator. (3) You can revise existing report forms using either Report Generator. The reports need not have been created originally with any particular report writer. How to run reports is explained in the end-user section of this User's Guide. The following two sections address how to create new report forms and revise old ones. 2.1.10.1.2 Creating A New Report Format After printing a listing of the file structure with which you will be working, the next step in creating a new report form is to select the R - Reports Menu option from the WAMPUM Main System Menu. In all versions, highlight Create New Report and press <ENTER>. Then enter the name you wish to assign to this new report form. Do not enter a file extension since WAMPUM automatically assigns .FRM as the file extension in keeping with the dBASE naming convention. WAMPUM then will run the Report Generator assuming you have sufficient memory to support it. As is true with the dBASE III report writer, WAMPUM Report Generators divides a report into three parts: 1. Page Heading & Format Settings 2. Break Level Controls 3. Report Column Contents & Headings The Page Heading & Format Settings screen allows you to specify the title of your report as well as the dimensions of the paper on which the report will be printed or displayed. You also indicate whether the report should be single or double-spaced and whether form feeds should be generated before and after a report is produced. Unlike dBASE III, WAMPUM always generates a form feed at the end of a report whether requested or not. This assures your printer always is at TOP OF FORM for the next job. For the Page Heading, 23 type in whatever title you want to appear at the top of your report when it prints out. Do NOT center the title since WAMPUM will do this for you automatically. If you want a multi-line heading, just type it the way it should appear at the top of each report page. Once you have entered a Page Heading, press the <ENTER> key to move to the Format Settings fields. There are eight options: 1. Enter page width . . . . . . 80 2. Enter left margin . . . . . . 8 3. Enter right margin . . . . . 0 4. Enter no. lines per page . . 58 5. Double spaced report? . . . . N 6. Page eject before printing? . Y 7. Page eject after printing? . N 8. Plain page . . . . . . . . . N Shown beside each of the above entries is the default value which will be used unless you change them. The Plain Page option controls whether a report heading with date prints at the top of each page of your report. For normal printers, the default settings usually are fine except you may wish to narrow the left margin to about 2 just to provide more report space for information. In addition, you may wish to change the page eject before printing option to N. For those using a laser printer, you will need to adjust the settings or your reports will run off the bottom of the page since most lasers force a 1/2 inch margin at the top and bottom of a page. With standard 10 pitch, portrait mode reports, the appropriate settings are 80, 2, 0, 56, and N or Y depending upon whether you want the report single or double-spaced. If you are printing sideways (landscape mode) with FONT8 (10 pitch) or with FONT9 (16 pitch), then the settings should be as follows: FONT8: 105, 2, 0, 40, and N or Y FONT9: 140, 2, 0, 40, and N or Y Once you have entered the Page Heading and report settings, press the <PgDn> key to display the second screen of the report generator. This screen is used principally to break reports into sections based upon a change in the value of some key field in the data base. For beginners, just press <PgDn> to skip this screen. 24 For experts, you should recall that your report will not break properly on the field specified in Group/Subtotal on unless that same field is the primary index in use when the report is run. Similarly, if you specify a subgroup field name, this must be a subfield in the primary index as well. An example may clear the air a little. Suppose we are producing a report of customers and we want the report paginated by zip code. Since we already have a ZIP index, the only trick is to assure that ZIP is the lead index when the report is run. To create the template, enter the following: Group/subtotal on: ZIP Summary report only? N Eject after subtotal? Y Group/subtotal heading: Zip Code: Subgroup/subsubtotal on Subgroup heading: What happens if you forget to set the primary index to ZIP? When the report is run, WAMPUM assumes you know what you are doing. So, as the report sifts through your data base, it will do just what you told it. Whenever, the zip code of customers changes, the report will issue a page break and print a new subheading of Zip Code: 30013 for the next zip code encountered. However, since you forgot to put the proper index in effect, the actual records in the data base will not be in zip code order. Thus, you may get a page with one customer from zip 98199, then a page with one from 30013, then another page with one from 98199, etc. In short, you probably will get about a 200 page report rather than the five page report you expected. As noted earlier, if you are a beginning report developer, skip this screen until you have an ample paper supply. The meat of the coconut in creating report forms is the Field Contents screen. This is the screen on which you tell the report generator which piece of information you want printed on the actual report. For example, let's assume we want our final report to be laid out as follows: Customer Name Purch Amt Purch Dt Married Comments For each column of information, you must specify a separate Field Contents screen. When you finish specifying one column of information, simply <PgDn> to get another screen. This process continues until you have specified all of the pieces of information to be printed in the various columns of your report. Note that each screen asks for five items of information: 25 1. CONTENTS 2. # decimal places 0 3. Totals? N 4. HEADER 5. WIDTH CONTENTS is asking for the data base field name of the field to print in the current column of the report. The CONTENTS field may contain any valid dBASE expression. In addition, you can force WAMPUM to create multi-line reports by specifying more than one field name for the contents field. Columns of a report are built from left to right across the screen or page when a report is produced. Since we want the customer's full name in the first column, we need to get a little fancy. If we only wanted the last name in this column, you would just enter LASTNAME since that is a field name in the data base. However, FULLNAME is not a field name in the data base. It has to be constructed by joining the last and first name fields together with a comma and space between them. We also want to strip the trailing spaces off the last names so we don't get a printout such as Smith , John. The correct syntax to extract full names is the following: TRIM(LASTNAME) + ", " + FIRSTMI Now press <DN> cursor key or <ENTER> to move down to the # decimal places field; however, the <DN> cursor is safer since a little Clipper anomaly sometimes assumes you're finished building your report when you press <ENTER>. This is not true in the FoxBASE+ versions. Unless you have specified a numeric expression for the CONTENTS, both the # decimal places field and the Totals? field should be left alone. If you are outputting numeric data, then the # decimal places field allows you to specify how many decimal positions should be printed for this column of the report. Simply enter a number and press the DOWN CURSOR. Totals? allows you to specify whether you want the numeric expression totaled (and subtotaled) at breaks in the report and at the end of the report. Note again that you cannot TOTAL anything except a numeric expression. If you just want a COUNT of records, this is covered below separately. Then, DOWN CURSOR to the HEADER field. HEADER is asking for the column heading to display for this column of the report. This is free-form text of your choosing. It should convey to the reader of the report what the contents of this column of the report actually are. The only precaution here is that the header typically should not be much wider in length than the maximum field width being 26 displayed in this column. Otherwise, you are just wasting space across the report since the WIDTH must be the wider of the field maximum width and the header width. In the example above, type Customer Name on the first header line, then press the DOWN CURSOR and type 42 hyphens on the next line to simulate an underscore. Use the DOWN CURSOR to move down to the WIDTH field. WIDTH is asking for the column width of this column of the report. As noted above, this width should be the greater of the field maximum width or the longest line of the column headers. For our full name, the width would be the sum of the widths of the LASTNAME field + FIRSTMI field + 2 (for the comma and space) = 42. Once you have entered the width desired, press <PgDn> or <ENTER> and a second Field Contents Screen will appear. For the next column of your report, the Field Contents would be PURCHAMT, the Number of Decimals would be 2, the Totals would be Y, the Header would be Purch Amt then 9 hyphens, and the Width would be 9. The only gotcha here is making sure the total column width can hold the totals calculation for the entire report. We will assume 9 will suffice. When the report is run, if you get a total with all asterisks, simply increase the column width to accommodate the total. For the third column, the Field Contents would be PURCHDT, the Number of Decimals would be 0, the Totals would be N, the Header would be Purch Dt then 8 hyphens, and the Width would be 8. Note that in reports you can perform calculations with date fields. For example, if an invoice always was due 30 days after the purchase date, we could change the Field Contents to PURCHDT+30 and change the Header to INVOICE DUE. When the report was run, the invoice due dates automatically would be calculated. For the fourth column, the Field Contents would be MARRIED, the Number of Decimals would be 0, the Totals would be N, the Header would be Married then 7 hyphens, and the Width would be 7. Notice that a logical field yields a result of .T. for true or .F. for false, 3 characters wide. But, the header is wider so the column width must be adjusted to accommodate the wider 7 character heading. Here you might prefer to print the word "Yes" or "No" rather than .T. or .F. WAMPUM supports this using the immediate IF function. The syntax for immediate IF is IIF(condition,true result, false result). In English, the immediate IF function first requires a Boolean logic condition. The second argument is what to do if the condition is true. The third argument is what to do if the condition is false. Thus, to test a logical field, the syntax is IIF(MARRIED,"Yes","No"). 27 For the fifth column, the Field Contents would be COMMENTS, the Number of Decimals would be 0, the Totals would be N, the Header would be Comments then 20 hyphens, and the Width would be 20. Since COMMENTS is a memo field, the column width can be adjusted as required to meet your needs. WAMPUM automatically will provide word wrap as necessary to make the COMMENTS field fit in the column width specified. With the Clipper Report Writer, you MUST ALWAYS move to a blank Field Contents screen before electing to SAVE your report template. If you violate this rule, you probably will lose the last column of your report. Press the <ESC> key to tell the report writer you are finished. You will be asked whether you are finished. Typing a Y saves the report template to disk. Typing an N returns you to the top of the current Field Contents Screen. Pressing <ESC> aborts the report creation process and does NOT save the report. What happens if you want to change something before you have first saved the report? With either report writer, simply press <PgUp> to move back through the screens you have already entered. Remember, however, that with the Clipper Report Writer, you must <PgDn> to return to a blank Field Contents Screen before SAVING the report. You probably will have to use the <ENTER> key to move through the last completed Field Contents Screen to get to a blank screen. Be aware that leaving an actual blank Field Contents Screen in the report template will cause a run-time error when the report is executed. Suppose you want to count the number of records output in the report. This is perhaps the weakest link in both the dBASE report writer and all the clones. The easiest method for doing this is to include a final Field Contents Screen with the following specifications. For the CONTENTS, type the number 1. For DECIMALS, leave it at 0. For TOTALS, type Y. For the HEADER, type TOTAL and a second row of -----. For width, type 5. This will tell WAMPUM to count the records as the report is produced and print a total at the bottom. It will also uglify your report by producing a column of 1's along the right margin of your report. Suppose you want a multi-line report with a name and address in a single column followed by several other pieces of data in separate columns. For the contents field, you may specify more than one field for output in the column so long as all the fields evaluate to character strings. To force multiple lines within a column, you simply reduce the column width to account for the amount of data which should display 28 on each line plus one space. Then adjust your various lines of data to match the column width. A simple example may help. Using our sample data base, the syntax for the Field Contents is SUBSTR(TRIM(LASTNAME)+", " + FIRSTMI + SPACE(20),1,41) + ADDRESS. The Column Width would be set to 41. This forces "word wrap" after 41 characters which will be where the full name ends and the address begins. The final thing to be careful of in creating reports is to make sure the total field widths specified for your report do not exceed the PAGE WIDTH specified when you set up the report. A little math in advance will solve this problem. WAMPUM always leaves a single space between columns of the report. This is in addition to the field widths specified! 2.1.10.1.3 Modifying Existing Report Formats To modify an existing report, select the R - Report Menu option from the Main System Menu. Look at the listing of reports which displays and write down the name of the one to be modified. With all versions, choose the Modify Report option and highlight the report you want to change. The discussion above with respect to creating a new report applies as well to modifying an existing one. As noted, be careful to check the defaults and make certain with the Clipper Report Generator that you have moved to the end of your existing report template and then to a BLANK CONTENTS field before saving the report template. 2.1.10.1.4 Outputting MEMO fields in Reports MEMO fields may be formatted as columns in a report just like a character string. The syntax of the CONTENTS expression is simply the name of the MEMO field. The field width may be adjusted to meet your requirements. Word wrap is automatic. 2.1.10.2 LABELS 2.1.10.2.1 Overview WAMPUM Label Templates are designed using either the Clipper LABEL Generator, which Nantucket generously has allowed us to distribute without charge, or the FoxBASE+ LABEL Generator which is part of the FoxBASE+ run-time module. WAMPUM requires 420K to access the Clipper label generator program from the Main System Menu. If you are short on memory, you may run the label program from the DOS prompt 29 using the following syntax: LABEL filename where filename is the name of the label template to be created or revised. This does not apply with FoxBASE+. Before you can create new label templates or revise old ones except with FoxBASE+ versions, you need to make sure the program LABEL.EXE is located in a directory supported by your DOS PATH command. This will assure that WAMPUM can access the label generator whenever you want to design or redesign a label form. You should also be aware that beginning with DOS 3.0, a DOS program named LABEL.COM is provided to rename volume labels. Make certain that your DOS PATH checks the subdirectory containing Clipper's LABEL.EXE program before checking the DOS subdirectory containing LABEL.COM. Otherwise, WAMPUM will execute the wrong program when you attempt to create or revise label forms. Another approach is to rename LABEL.COM to some other file name such as NEWLABEL.COM. This will avoid conflict. Before designing labels, you will always want to print out a listing of the file structure with which you will be working. Pick the S - Select Utilities option and specify T or Y for the List File Structure option. Then type Y when asked whether to print the structure listing. Just as was true with reports, a label form is a file which contains instructions telling WAMPUM which pieces of information you want to extract from a data base and place on labels. All WAMPUM labels must have a DOS-standard file name with no file extension. As is true with dBASE, WAMPUM supplies a file extension of .LBL with label forms. The L - LABELS for Mail option on the WAMPUM Main System Menu provides three capabilities to the user. (1) You can run any existing label form created with any dBASE III-compatible Label Generator. (2) You can create new label forms using either the Clipper or FoxBASE+ Label Generator. (3) You can revise existing label forms using the Clipper or FoxBASE+ Label Generator. How to produce mailing labels is explained in the end- user section of this User's Guide. The following two sections address how to create new label forms and revise old ones. 30 2.1.10.2.2 Creating A New Label Format After printing a listing of the file structure with which you will be working, the next step in creating a new label form is to select the L - Labels for Mail option from the WAMPUM Main System Menu. In all versions, pick Create New Labels and press <ENTER>. Then enter the name you wish to assign to this new label form. Do not enter a file extension since WAMPUM automatically assigns .LBL as the extension in keeping with the dBASE III Plus. WAMPUM then will run the Label Generator assuming you have sufficient memory to support it and (except for FoxBASE+ versions) assuming WAMPUM can find Label.Exe in the DOS PATH before finding DOS's LABEL.COM program. As is true with the dBASE III label writer, the WAMPUM divides a label form into two parts: 1. Label Settings 2. Label Contents There are six items of information which can be set to specify how the labels should be formatted. These include: 1. Width of Label 35 2. Height of Label 5 3. Left Margin 0 4. Lines Between Labels 1 5. Spaces Between Labels 0 6. No. of Labels Across 1 Width of Label refers to the maximum width of any text entry on any label produced. Height of Label means the maximum number of lines per label. Left Margin is the starting column position for the left-most label. Lines Between Labels specifies the number of blank lines between each completed label. Spaces Between Labels is the number of blank columns horizontally between labels when two or more are produced across the page. Number of Labels Across allows you to specify how many columns of labels will be printed across the page (up to 5). The main consideration to keep in mind in producing labels is that there is no pagination control for labels. All label forms assume an unending supply of continuous-form label stock in your printer. If you are using a laser printer, then printer codes will have to be used to set top of form and page length to match the label format desired with one exception. WAMPUM knows the format for 33-UP LABELS 31 (11 labels per page with 3 across) if you use the following settings for the label form and specify FONT7 with the HPLASERA printer table: 1. Width of Label 24 2. Height of Label 4 3. Left Margin 0 4. Lines Between Labels 2 5. Spaces Between Labels 4 6. No. of Labels Across 3 Once you have entered the label settings desired, press <PgDn> to move to the Label Contents Screen. In this screen, you enter field names to be produced on the labels much as was done on the Field Contents Screen with Report Forms. Then, except with FoxBASE+ versions, press <ESC> when you have completed filling out the field expressions which should appear on each line of the label. You will be prompted to answer whether to save the new label format. A typical example of field expressions for mailing labels follows. All of the names in BOLD are the actual field names from our sample data base: 1 TRIM(FIRSTMI) + " " + TRIM(LASTNAME) 2 ADDRESS 3 TRIM(CITY) + ", " + TRIM(STATE) + " " + ZIP 2.1.10.2.3 Modifying An Existing Label Format To modify an existing label format, select the L - Labels for Mail option from the Main System Menu. Look at the listing of labels which displays and write down the name of the one to be modified. In all versions, choose Modify Label, then pick the label template to be modified. The discussion above with respect to creating a new label applies as well to modifying an existing one. You then SAVE or ABORT saving the revised label form just as was done in creating a new one above. 2.1.10.3 FORM LETTERS 2.1.10.3.1 Overview One of the most critical limitations of dBASE III has been its lack of a convenient "mail merge" interface which would allow selected data to be extracted from a data base and inserted into form letters. WAMPUM provides this link through its built-in Form Letter generator. 32 In FoxBASE+ versions, a WAMPUM form letter is nothing more than a standard dBASE III data base with a single field designated as LINE1. In other versions, the form letter file is a standard ASCII file which can be created using any editor or WAMPUM's built-in editor. When a form letter merge is executed through either the T - Form Letter option or via W - Wampum Preformatted Output, WAMPUM simply extracts data from your data base and merges it with the text contained in the form letter file you specify. WAMPUM automatically handles word wrapping as part of the merge process. In addition, the Form Letter Generator includes powerful programming functions which allow you to test the contents of fields in a data base and branch to various paragraphs of the form letter depending upon the contents of the data base. The default page size for form letters is 8-1/2 x 11 using 10 pitch type. You may adjust the left and right margin settings in either the WAMPUM Configuration Screen or within the form itself. You also may turn off form feeds at the end of each document if desired. Up to five related data bases can be manipulated within any form letter file. You also may now rely upon indexed key retrieval to generate single form letters from any active data base. This avoids having to make a full pass through very large data bases to generate only a few form letters. The following sections describe how to create form letters. The end-user section of this Guide describes the process of actually merging data with a form letter file. 2.1.10.3.2 Creating a New Form Letter File To create a new form letter, select T - Form Letter Menu from the Main System Menu. In FoxBASE+ versions, when prompted for the name of the form letter to run, type an asterisk (*) and press <PgDn>. In other versions, choose Create/Edit Form. You then will be prompted to name the new form letter. In FoxBASE+ versions, this name must start with T- and then up to a 6 character name. WAMPUM will add the .DBF file extension and build the form letter file. In other versions, the ASCII file name may be any DOS file name up to 8 characters. WAMPUM will add the .TXT file extension and run WAMPUM's built-in editor. 2.1.10.3.3 Building Data in Form Letter Files To actually build the form letter in FoxBASE+ versions, use F - File Select to select the form letter file created 33 above just as you would select any other data base to use. In other versions, the form letter editor is activated when you create or edit any form letter file. Before actually entering data for the form letter, some explanation of how form letters are constructed and how they are output will assist in your design. When WAMPUM generates form letters, it reads the form letter file to get the text for the form letter. In FoxBASE+ versions, all leading and trailing spaces in each record are stripped off when WAMPUM builds the text to print. WAMPUM then reads the next record in the form letter file and appends it with a single leading space to what was in the previous record. For example, each field in a FoxBASE+ form letter record may contain up to 136 characters. Suppose the following two records were in the file: Hello there, Cutie! When this form letter was printed, the text would read: Hello there, Cutie! Note that there would be no indentation from the left margin, and all other spaces would be trimmed except the one space added between the two records. When you really want spaces in FoxBASE+ version form letters, insert CHR(255) on the left margin of a record. Then it can be followed by as many spaces as desired. To insert this character, hold down the ALT key and type 255 with the numeric keypad. Clipper and dBASE-compatible index versions of WAMPUM use standard ASCII documents which, when merged, are printed exactly as they are created except merge text is inserted into the form letters as coded. All WAMPUM Form Letters may contain special markers (field data expressions) which tell WAMPUM to extract or evaluate information in the primary data base when the form letter is merged. In FoxBASE+ versions of WAMPUM, you may have only one field data expression in each record of the form letter file. In other versions, there are no limitations on number or spacing of field data expressions. A FIELD DATA EXPRESSION always begins and ends with //. In its simplest form, an expression such as //LASTNAME// would tell WAMPUM to extract the contents of the LASTNAME field in the current record and insert it 34 into the form letter at this place. The beginning and ending //'s must be part of the same record in FoxBASE+ versions. In FoxBASE+ versions only, you may block off a section of text in the form letter which will be affected by the evaluation of the expression itself. For instance, if a particular field is blank in the data base, the form letter may contain a special code telling WAMPUM to omit all of the text which has been blocked off. TEXT MARKERS consist of @@ at the beginning and ending of the affected text. Note that these markers may not extend beyond a single record. Thus, you cannot have one pair of @'s in record 5 and the other pair in record 6. An equivalent functionality is available in other versions using the immediate IF function specifying the text to be printed if the condition is true or false. An example of the FoxBASE+ syntax would be the following. Suppose you want to thank people for contributing to your reelection campaign. In your data base is a field CONTRIBDT which will be empty if no contribution has been received. The record entry in the form letter might say: @@Thanks for being a supporter!//*CONTRIBDT//@@ This entry means if CONTRIBDT is not blank, then print the text: Thanks for being a supporter! Otherwise, leave this sentence out of the form letter entirely. In other versions, an equivalent entry would be the following: //=IIF(.NOT. EMPTY(ContribDt),"Thanks supporter!","")// The following section describes all FIELD DATA EXPRESSIONS implemented to date. See the README.DOC file for any additional enhancements. Another difference in FoxBASE+ Form Letters and other version form letter text is that the FoxBASE+ version needs to know when you really do want to end a paragraph. This is referred to as a hard carriage return with many word processing packages. WAMPUM FoxBASE+ versions interpret a blank record in the form letter file or a record beginning with a tilde (~) as a hard carriage return. Note that if you want a hard return in a form letter and a blank line between paragraphs, you will need to insert two blank records in the form letter file or two records beginning with a tilde. All text following a tilde is ignored if the tilde is the first character on the line. Finally, remember that WAMPUM form letters are built on the fly when you actually run the form letter program. Make certain that you end all form letter files with at least one blank line or record and preferably two. This will assure 35 that the form letter buffer is purged before the next form letter is produced. 2.1.10.3.4 WAMPUM Field Data Expressions What follows is a listing of the syntax for various FIELD DATA EXPRESSIONS together with an example of each expression. The best way to get a feel for using WAMPUM Form Letters is to build a few. It provides more power and flexibility in this area than any commercial product on the market. Like any powerful programming tool, however, it takes a little getting used to. //LASTNAME// Allows imbedding a character, numeric, or date field within a form letter record. It would output Jones if Jones were in the LASTNAME field. Note: if a date field, it outputs the date in the format May 21, 1986 if entry is 05/21/86. @@Thanks //LASTNAME//.@@ (FoxBASE+ versions only) Allows imbedding a CHARACTER FIELD with a string of text which will print only if the field is not blank. It would output Thanks Jones. if Jones were in the LASTNAME field. @@Filed.//*FILINGDT//@@ (FoxBASE+ versions only) Tests whether a particular character, numeric, or date field is not blank or whether a logical field is True. In either case, if True the output would be Filed. Otherwise, nothing would be printed. @@Not filed.//#FILINGDT//@@ (FoxBASE+ versions only) Just the opposite of the above. If the character, numeric, or date field is empty or if the logical field is False, the expression is printed. Otherwise, nothing would be printed. @@A new baby!//?PREGNANT//@@ (FoxBASE+ only) Similar to above. Used only with a logical field. If logical field is True, the expression is printed. 36 @@So you're 30.//!AGE=30//@@ (FoxBASE+ only) Allows any dBASE III expression as the test for whether the text should be printed. If the test is True, the text is printed. Make certain that both sides of the expression are of the same data type. This example would print So you're 30! if the AGE numeric field = 30. // AGE=30// (FoxBASE+ versions only) This is the syntax for a GOTO using the WAMPUM form letter generator. Note the SPACE at the beginning of the expression which means, IF the expression is True, SKIP to the next record beginning with a SPACE character. If you want to skip past a required carriage return record, make certain that the record begins with a tilde and not with a SPACE since blank records are assumed to be those containing all spaces. //+SAMPLE.DOC// With lengthy pieces of text with no embedded data, it is often easier to type them into a plain ASCII document using a text editor. You then can merge them into a WAMPUM form letter with the syntax shown which says read in the SAMPLE.DOC text file at this point in the form letter. Note that this command should appear in a record by itself with no other text. //=DTOC(DATE())// There may be times when you just want to reformat some data directly out of the data base. The = operand allows this to be done with any dBASE expression so long as it evaluates to a STRING EXPRESSION when it is processed. //<#,filename,indexname// Using the < command allows you to open up to 5 related data bases from within a form letter file. Replace the pound sign (#) with a number from 5 through 9. Note that 5 corresponds to the number of the related data base opened with the Zoom/Relate File option. It need not be reopened. Paths may be included in identifying both the filename and the indexname. 37 //>#,string expression// Using the > command permits you to do an indexed SEEK by key value to any record in the file identified by the number replacing #. This numbered file and a corresponding index must already have been opened using the < command. The string expression may be the contents of a field in the primary data base or any dBASE string expression. If the name of a field in the primary data base is used, be sure to precede it with the ALIAS for the file using the following syntax: ALIAS->fieldname where ALIAS is the actual file name of the primary data base and fieldname is the legal field name of a field in the primary file. Once the SEEK has been accomplished, any data in the secondary data base may be extracted using the = field data expression outlined above and the ALIAS->fieldname syntax where ALIAS is the name of the secondary data base file and fieldname is the name of a field in that file. //FF// The FF command allows the user to generate a form feed or page eject from within a form letter file. //NOFF// The NOFF command turns off automatic form feeds which normally are generated after each record is processed. //@LMargin,RMargin// Permits the resetting of the default left and right margin within a form letter. It can only be reset once, and it applies to the entire form. For example, //@15,70// would reset the left margin to 15 and the right margin to 70. //}LABEL,Logical Expression// (Clipper/dBASE versions) Provides a functionality equivalent to BASIC's IF .. THEN .. GOTO. LABEL is the name of the WAMPUM LABEL to jump to when the specified Logical Expression evaluates True. The syntax for the GOTO LABEL is //{LABEL}//. For example, //}CHEAPSKATE,PurchAmt=0// would instruct a form letter to jump to //{CHEAPSKATE}// if the value of the PURCHAMT field equates to 0. 38 2.1.11 Building Function Key Macros (KEYS.DBF) As an aid in data entry intensive applications, WAMPUM provides the capability to define up to 39 keyboard macros (9 in FoxBASE+ versions) which may be invoked by the end-user simply by pressing a function key. As is true with WAMPUM applications in general, these keyboard macros are application specific. This means that a set of keyboard macros may be defined for every application in each new directory created on your disk. The name of the file which stores the macros is KEYS.DBF which is a standard dBASE III data base file. It is created automatically whenever WAMPUM is first run in a new subdirectory. To build the table of macro definitions, follow the steps below. First, select the KEYS.DBF file as the file with which you want to work by picking the F - File Select option on the Main Menu. Enter the file name KEYS when prompted to do so. When the Main Menu reappears, the bottom line of the screen should say: FILE: KEYS Next, you will want to figure out what keystrokes you want to store under which function keys. The following function keys are available for use: F2 - F10 Shift F1 - Shift F10 (except FoxBASE+ versions) Ctrl F1 - Ctrl F10 (except FoxBASE+ versions) Alt F1 - Alt F10 (except FoxBASE+ versions) Function key F1 is reserved by WAMPUM for HELP. Record numbers in the KEYS file match the function keys by key number. See the table below: Function Keys Record Numbers F2 - F10 Rec # 2 - 10 Shift F1 - F10 Rec # 11 - 20 Ctrl F1 - F10 Rec # 21 - 30 Alt F1 - F10 Rec # 31 - 40 Thus, whatever keystrokes are entered in record 5 of the KEYS file will automatically be assigned to function key F5. Those in record 40 will be assigned to function key ALT- F10. Any record in the KEYS.DBF file which is blank will be ignored. 39 There are two rules to remember in entering data in the records of the KEYS file. (1) Record 1 of the KEYS file is always ignored since it corresponds to the HELP function key, F1. (2) Every entry in the KEYS file must equate to a CHARACTER STRING when evaluated by WAMPUM. The first rule is only logical. Since F1 is reserved for HELP, the corresponding record in the KEYS file is ignored. Note that you will have to ADD a first record which automa- tically will be record 1. Simply press <ENTER> to save it and create record 2 which can be used for function key F2. The second rule is critical because if it is violated you will get run-time errors the next time WAMPUM is started. If this happens, simply ignore each error (which means that function key will not be set), then edit the records causing the problems following the steps outlined above. Translated into dBASE III lingo, each record in the KEYS file must be a character string. If it is simply character data, you meet this requirement by enclosing the data in double or single quotes. If you have single quotes in the string, then enclose the string in double quotes and vice versa. You can also use dBASE III functions and special WAMPUM functions to create macros so long as the expression evaluates to a string. Here are examples to get you started: DTOC(DATE()) would convert today's date to a character string and store it as a macro in the following format: 10/10/86. FULLDATE(DATE()) would store today's date as a macro in the following format: October 10, 1986. DTOC(DATE()+30) would store today's date + 30 days. CDOW(DATE()) would store the day of the week for today in a macro in the following format: Tuesday. STR(YEAR(DATE()),4) would store this year as a string in the following format: 1988. DTOC(WeekDay(DATE()+30)) would store the date 30 days from today rolled over to Monday if it hits on weekend in the following date format: 10/10/86. To convert the WEEKDAY expression to a date required that it be preceded by DTOC(). 40 Again, the important thing to remember is that character text must be enclosed in quotes, and data other than character data must be converted into a character string using a dBASE III or WAMPUM conversion functions. Note that keyboard macros do not take effect until the next time WAMPUM is started from DOS. They will be loaded on each subsequent running of the program unless changed. Developers should be careful not to store a file named KEYS.DBF in the DOS PATH unless you intend to invoke the macros contained therein whenever an application starts and a file named KEYS.DBF cannot be found in the default directory. 2.1.12 Building Edit Checks (EDIT.DBF) As an aid in data entry accuracy, WAMPUM provides the capacity to design custom edit checks for each WAMPUM application. As was true with keyboard macros, a set of edit checks may be defined for each application in each new directory created on your disk. The name of the file which stores the edit checks is EDIT.DBF which is a standard dBASE III data base file. It is created automatically whenever WAMPUM is first run in a new subdirectory. To build the table of edit checks, follow the steps below. First, select the EDIT.DBF file as the file with which you want to work by picking the F - File Select option on the Main Menu. Enter the file name EDIT when prompted to do so. When the Main Menu reappears, the bottom line of the screen should say: FILE: EDIT Next, figure out what edit checks need to be developed for the particular application. For some applications, you may want to assure that a data entry field is never left blank. For others, you may want to assure that a duplicate key is never entered. Finally, you may want to assure that any field entry is contained in a table of valid entries. None of these checks are possible in dBASE III without substantial custom programming. WAMPUM provides this capability with a couple minutes work. The EDIT file structure consists of two fields: EDITTEST and ERRMSG. The theory behind WAMPUM edit checks is a simple one. Once you "turn on" the edit checks for use against a particular file, WAMPUM automatically tests newly added records as well as updated existing records to make certain that they do NOT violate any of the error conditions 41 (EDITTESTs) you have specified in the EDIT file. The checks are only run when new records are added to a data base or existing records are changed. For each error condition identified, WAMPUM will display an error message (ERRMSG) and then permit the end-user to fix the problems. The end- user cannot SAVE the record with errors without correcting them. The end-user may <ESC>ape from a data entry screen without invoking WAMPUM's edit checking. In the FoxBASE+ versions only, edit checks are not invoked when a user enters data while in full browse mode. Since developers typically work with several files in creating a new application, there are some instances in which you would not want the edit checks to execute. Most impor- tantly, when the primary data base is not being used, you would not want to invoke a series of edit checks designed to check primary data base information. This is handled in a simple way. WAMPUM always reads the EDITTEST field entry in the first record of the EDIT.DBF to ascertain the name of the file to be checked. If this entry does not match in UPPER CASE the name of the current file in use, the edit checks are turned off. Stated somewhat differently, the EDITTEST field of Record 1 of EDIT.DBF is reserved to hold the UPPER CASE name of the data base to be edit checked. Thus, in the case of our example, the entry in Record 1 of EDIT.DBF should say CUSTOMER. If you forget to enter the name of the data base file to be checked in record 1, then obviously the edit checks specified will never be invoked! There also may be occasions where you want to specify the actual fields to be displayed with BROWSE MODE ON rather than accepting WAMPUM's default which is the first few fields in the actual data base structure. If you want to specify your own fields, insert the following in the ERRMSG field of Record 1. The first character must be an asterisk (*). It is followed by the field numbers (from your file structure listing) of the fields you want displayed. All numbers must be three characters wide and should be padded to the left with spaces. Three digit numbers should be preceded by a single space. For example, if you want the fields LASTNAME, FIRSTMI, and ADDRESS to display in BROWSE mode and these are fields 1, 2, and 3 in your data base, the correct syntax would be: * 1 2 3. There are three things to keep in mind in developing your edit checks. (1) Edit checks must be dBASE III or WAMPUM expressions which can be evaluated as True or False. 42 (2) If the expression in EDITTEST is true, the error message in ERRMSG is triggered. In other words, you are building expressions which identify when an error condition occurs rather than the other way around. (3) And most importantly, if you wish to evaluate data entered in a particular field, you do NOT use the fieldname to test for an error. Instead you use the field's sequential number in the data base in conjunction with an array named FLDDATA() for FoxBASE+ versions or FLDDATA[] for other versions. This paragraph will clear up any confusion you are momentarily experiencing. Since you need to know a field's position in the file structure in order to develop edit checks, your first step should be to print out the file structure of the file which will be checked. Pick the S - Select Utilities option after making certain that the correct file is in use. Change the List File Structure option to T or Y, then answer Y when prompted for whether to print the structure. This will give you the list of fields in the data base. Note that the left column shows the field's NUMBER in the structure. Let us assume that the LASTNAME field is field number 1. An appropriate edit check to assure the LASTNAME field was not left blank would read as follows: FLDDATA(1)=SPACE(20) in FoxBASE+ versions, or FLDDATA[1]=SPACE(20) in other versions. One of the above entries should be entered as the EDITTEST entry in the EDIT file. The ERRMSG field entry might say something like this: The LASTNAME field cannot be left BLANK. Whenever the EDITTEST record evaluates to TRUE, meaning the LASTNAME field is all spaces, then the ERRMSG would be displayed. The important thing to remember is to use the appropriate array name and not LASTNAME in identifying the field to be checked! Note that you also can check one field against another in the same data entry screen. For example, assume there were two fields in the data base as follows: 1 TRANSCODE Character 8 2 TRANSDATE Date 8 Let's assume that the format of the TRANSCODE entries is of the form: 88-12345 where 88 identifies the year of the transaction. One edit check you probably would want to perform in a situation such as this is to make sure the first 43 two digits of the TRANSCODE matched the year in the TRANSDATE field. Here is one possible way to handle this: Substr(FldData[1],1,2)<>Substr(DTOC(FldData[2]),7,2) Note in the example that the relationship must be coded so that when it is TRUE, the error message displays. Thus, we want to code it in such a way that when the first two characters of the TRANSCODE do not match the year in the TRANSDATE, the expression is True and hence the error message is given. Note also that the expressions on both sides of the relational operator must be of the same type. In this case, both are character strings. The DTOC() function converts a date expression to a character string. Finally, it should be noted that these EDIT CHECKS will not take effect until the next time WAMPUM is run with the appropriate file in use. They will be loaded on each subsequent running of the program unless changed. Creating Calculated Fields To automatically calculate the value for a field, that field must be one of the fields in the active data base. Typically, you would NOT want it to display on a data entry screen since its value will be changed automatically regardless of what the user enters. This calculation capacity may be used to compute both dates and numeric values and if necessary can also be used to compute values for character and logical fields. To automatically calculate the value for a field, follow these steps: (1) In the EDITTEST field, the first character must be the equals sign (=). This is followed by whatever selection criteria will be used to determine when the calculation IS performed. If you want it done whenever a record is added or changed, then the EDITTEST field should look like the following: =.T. Note: WAMPUM keeps track of what mode it is in by setting a variable HELPCODE to the number corresponding to the option picked from the Main System Menu, e.g. A - Add is 1, E - Edit is 2, etc. You may find it helpful to be able to perform calculated field transactions only when the user is in Edit mode or Add mode. If you only wanted a field calculated when a new record was added, use the following syntax in the EDITTEST field: =HELPCODE=1 (2) In the ERRMSG field, two codes must be inserted and they are separated by a comma. The first is the field 44 number corresponding to the field to be calculated. Now type a comma. Then enter any valid dBASE expression to handle the calculation desired. A simple example may help. Assume that a data base contains a FILINGDT field as #1, a DAYSPEND field as #14, and a CLOSEDT field as #20. Until a closing date entry has been made, we want the computer to recompute the days pending from the filing date whenever a new record is added or changed. The field entries should look like this: EDITTEST: =EMPTY(FLDDATA[20]) ERRMSG: 14,DATE()-FLDDATA[1] Using "Table-Lookup" for Editing Table Lookup for Editing means the ability of a data base system to refer to a table of values in order to determine whether a value entered by a user is acceptable. Within WAMPUM, table-lookup is implemented using standard dBASE data bases for the tables. These data bases may be checked either sequentially or through an index file as the developer desires. To perform "table lookup" as part of the edit checking process, the following rules must be met: (1) In the EDITTEST field, the first character must be a question mark (?) if a non-indexed dBASE file will be used as the table. Or two question marks (??) must be used if a dBASE file table will be checked using a WAMPUM index as the key. The question mark or marks are followed by whatever selection criteria the developer wants to specify to tell WAMPUM when the table lookup should be performed. See the examples. (2) In the ERRMSG field, three values must be inserted with a comma between the values. (a) The first code is the number of the field to be checked against the table. Then type a comma. (b) The second code is the dBASE file name of the table to be checked (without the .DBF extension). Then type a comma. (c) The third code is one of two values. With a non-indexed table lookup (?), the third code is the name of the field in the table lookup file to be compared. With an indexed table lookup (??), the 45 third code is the name of the WAMPUM index file (without file extension) to use for the lookup. An example may help remove some of the mystery. If your main data base has a field #5 for the user to enter the abbreviation of the STATE where the customer lives, we want to make sure this entry is, in fact, a state in the United States. Using WAMPUM, you build another data base with a file name of STATES and an index called ABBREV which holds the two character abbreviation for each state in the United States. Your entries would look like the following in the EDIT record: EDITTEST: ??.T. ERRMSG: 8,STATES,ABBREV Using "Table-Lookup" for Calculated Fields Just as a table can be checked to verify data in your data bases, WAMPUM also permits table-lookup to actually calculate the contents of fields in your primary data base. The table may be accessed either sequentially or through a WAMPUM-index file as the developer desires. To calculate a table follow these simple steps in adding an entry to the EDIT file: (1) In the EDITTEST field, the first character must be an exclamation point (!) if a non-indexed dBASE file will be used as the table. Or two exclamation points (!!) must be used if a dBASE file table will be referenced using a WAMPUM index as the key. The exclamation point(s) are followed by whatever selection criteria the developer wants to specify to tell WAMPUM when the table lookup calculation SHOULD be performed. (2) In the ERRMSG field, five values must be inserted with a comma between the values. (a) The first code is the number of the field in the primary data base to be used to find a match in the table. Then type a comma. (b) The second code is the dBASE file name of the table to be checked (without the .DBF extension). Then type a comma. (c) The third code is one of two values. With a non-indexed table lookup (!), the third code is the name of the field in the table lookup file to be 46 compared. With an indexed table lookup (!!), the third code is the name of the WAMPUM index file (without file extension) to use for the lookup. Then type a comma. (d) The fourth code is the number of the field in the primary data base to be calculated from the table. Then type a comma. (e) The fifth code is any legal dBASE expression which specifies the value to be calculated for the field referenced in (2)(d) above. This expression would include references to one or more fields in the table typically. By way of example, let us assume that a company maintains an ORDERS file with numerous pieces of information being captured about new orders. Among these are the part number (field #1) and the part cost (field #2). There also is a table of PARTS which contains the cost of each part (PARTCOST) in the company's inventory. The developer wants to look up the cost of the part specified in the ORDERS file and insert it automatically into the part cost field in the ORDERS file. The syntax to do this using a PARTS file indexed on part number would look like this: EDITTEST: !!.T. ERRMSG: 1,PARTS,PARTNO,2,PARTCOST 2.1.13 Building Data Entry Menus (MENUS.DBF) WAMPUM supports three different types of data entry menus: (1) automatic; (2) semi-automatic; and (3) user- defined. FoxBASE+ versions also support standard dBASE format files. Automatic means if the developer does not create one or more data entry screens, then WAMPUM will automatically build a data entry screen permitting data entry and retrieval from every field in the active data base. Semi-automatic means that the developer may specify one or more fields to be displayed on each of 9 data entry menus. These values are stored in the MENUS.DBF file. WAMPUM will read the listings of fields selected by the developer and will generate an appropriate data entry screen to display the selected fields. 47 User-defined means the developer may choose to define all prompts and all locations for data on the data entry screen for up to 9 data entry menus. WAMPUM then will build a screen to match exactly what was defined. In FoxBASE+ versions, this screen may have multiple pages if a standard dBASE format file is used. Semi-Automatic Data Entry Screens Up to 9 semi-automatic data entry menus may be built for any given application. These typically correspond to different stages in the data entry process for a given data base. In addition to these 9 data entry menus, WAMPUM also provides the standard data entry screen which includes access to every field in the current data base. These data entry menus are numbered 0 to 9 with 0 being the default automatic menu with access to all fields. In addition to specifying up to 9 custom menus, developers may also restrict users without the developer password to a given range of menu numbers. Thus, some care must be exercised to group the restricted and non-restricted menus into contiguous numbers. A range of 1 to 5 is permissible, but you cannot allow access to menu 0 as well as access to menus numbered 2 through 6. Information pertaining to the custom menus is stored in a standard dBASE file named MENUS.DBF which is created in the current default directory whenever WAMPUM is first invoked. Each record in the MENUS file corresponds to a custom menu with the same number. Thus, record 1 contains information about menu 1, and so on. To build one or more semi-automatic menus, first start up WAMPUM in Developer Mode by specifying the developer password after the word WAMPUM. Make certain that the File in Use at the bottom of the screen is the one for which you want to build the custom menus. If so, choose S - Select Utilities and change the List File Structure field entry to T. Then <PgDn> and print the file structure for reference. When the Main System Menu reappears, pick F - File Select and enter the file name of MENUS. Press <ENTER> and WAMPUM will open the MENUS file. When the Main System Menu reappears, make sure the bottom line of the screen shows the file name MENUS. To ADD a new semi-automatic menu, pick A - Add Records from the Main System Menu. A blank record will appear with two fields: MENUNAME and FLDLIST. As the name suggests, MENUNAME is whatever name you want to 48 assign to this custom menu, CUSTOMER OPENING MENU. Enter the title desired and press <ENTER> to move to the FLDLIST field. In FLDLIST, you specify the field numbers corresponding to the fields you want displayed on the data entry screen. The sequence used to specify the numbers does not matter since the fields always are ordered according to their numeric position in the data base structure. The format for these field numbers, however, is CRITICAL! Rule 1: Each field number must be AT LEAST 3 characters in length with spaces to the left of the number to "pad" it to 3 characters. For example, field 1 would require that you type two spaces and then the number 1. 27 would require one leading space and then 27. Rule 2: Each field number must be preceded by at least one space. Field 106 would require space then 106. Rule 3: As many fields may be specified as will fit within the FLDLIST field observing the two rules above. For example, to create a data entry menu with fields 1, 7, 21, and 107, FLDLIST should look like the following without the quotation marks which have been included only to assist in showing the spaces: " 1 7 21 107" Once the FLDLIST field has been specified, press CTRL-W or <PgDn> to save the entry. A new blank record will appear. You may continue to add menus or <ESC> to exit to the Main System Menu. Once semi-automatic menus have been defined, you must configure them for end-user access to your application. This is covered in detail following the next three sections on building and linking custom data entry screens. If you are not creating custom data entry screens, skip to the section entitled Configuring Menus For End-User Access. Building Custom Data Entry Screens WAMPUM provides the ability to fully customize data entry screens. In addition, in FoxBASE+ versions, a standard dBASE format file may be used to develop multi-page data entry screens. With custom data entry screens, the developer has complete control over the following functions: 49 1. Specifying & Positioning of User Prompts 2. Specifying & Positioning of Fields 3. Picture Statements for Fields 4. Read-Only Access to Fields 5. Default Values for Fields Customizing data entry screens involves two steps: (1) building the customized screen and (2) linking the screen to the desired application. Building WAMPUM Customized Screens Building a WAMPUM customized screen requires the developer to create an empty dBASE III data base with the following file structure. Use B - Build New File to create it. FIELD NAME TYPE LENGTH DEC PROMPTROW N 2 0 PROMPTCOL N 2 0 PROMPT C 45 0 FLDROW N 2 0 FLDCOL N 2 0 FLDDATA N 3 0 FLDPIX C 73 0 READONLY L 1 0 DEFAULT C 60 0 The file name for this data base depends upon which of the 9 available menus you are creating. For the first menu, the file name must be MENU1.DBF. For the second, it's MENU2.DBF. The rest should be fairly obvious. Once the data base structure is built, use F - File Select to choose the data base. Then A - Add New Records to the data base for each prompt and/or field to be displayed on the data entry screen. For each record, you may specify either a prompt or a field or both to be displayed on the screen. A brief description of the contents of each field follows. PROMPTROW contains the row number where the prompt should be displayed. Allowable values are 1 through 24. PROMPTCOL contains the column number where the prompt should be displayed. Allowable values are 0 thru 79. 50 PROMPT is the actual text to be displayed on the screen. Typically, it would be the name of a field. Although, it can be any text desired. If you will be using plain text, then you may simply type the text in this field with quotes. FLDROW is the row on which a field should be displayed for data entry. Allowable values are 1 through 24. FLDCOL is the column position for display of a field. The allowable values are 0 through 79. FLDDATA is the field number of the field from the active data base to be displayed. This number appears on the left column of the List File Structure listing. FLDPIX is a dBASE picture statement specifying how the field should be displayed on the screen. Consult a dBASE reference for a complete listing of picture statements. The principal ones include one of the following characters for each byte to be displayed: A - Allows only letters 9 - Allows only numbers X - Allows any character Y - Allows only Y or N N - Allows numbers and letters L - Allows only logicals Any other character in a picture statement specifies a constant, meaning that WAMPUM will not allow the user to input a value other than the one specified. For example, 99/99/99 would be a typical picture statement for a date. READONLY is a logical field. If it is marked True, then the field specified in this record will be displayed but cannot be modified by the end-user. DEFAULT allows the developer to specify a default value for the field in add mode only. The contents of DEFAULT must be a dBASE expression matching the type of the field chosen in this record. For example, if the field to be displayed were a DATE field, then the expression must evaluate to a date. DATE() would tell WAMPUM to enter today's date as the default for a particular date field. NOTE: In specifying character field defaults, make certain the string is in quotes and matches the length of the field in the data base! Much of the agony of creating customized data entry screens can be avoided by using MenuMaker, a screen and menu generator, which is available from Ward Mundy Software. Simply draw the screen, and MenuMaker writes all necessary program code to generate the screen. 51 Linking Custom Screens to an Application Once custom data entry screens have been created, the developer next must link these screens to the actual data base application in which it will be used. First, pick F - File Select to choose the MENUS data base. Then, add or edit a record in this file corresponding to the menu number assigned to your custom screen. For example, if the custom screen was named MENU8.DBF, then there must be a corresponding record number 8 in the MENUS data base. If you don't have that many records added to the data base, then use A - Add Records to add it. Once positioned in record 8, enter a name for this custom menu in MENUNAME just as was done for the semi- automatic menus. In the FLDLIST field, simply type a single asterisk (*) if you are using a WAMPUM Data Entry Screen data base. Type a pound sign (#) if you are using a dBASE- compatible format file. Then save the entry. This tells WAMPUM to find the corresponding custom menu matching this record number at run time. Continue to make entries in the MENUS data base for each custom menu designed. You may mix both types of custom screens in FoxBASE+ versions. Next we must configure WAMPUM for end-user access to a range of menus. This applies for both semi-automatic and custom data entry screens. The steps are as follows: Configuring Menus for End-User Access Assuming you have saved a default configuration, in FoxBASE+ versions, press <ESC>ape and then <ENTER> to reload the default configuration. In other versions, press ALT- 0 to reload the default configuration. When the Main System Menu reappears, pick S - Select Utilities and mark the Change Current Menu field as True and <PgDn>. Three fields will appear below the menu list: (1) Number of current menu to use (2) Minimum menu number (3) Maximum menu number Press <ENTER> to skip through the current menu field. Then enter values for the minimum menu number and the maximum which correspond to the menus you have created and to which you want the users to have access. Remember that if the minimum number is 0, users will be able to access and 52 change every field in the data base! Make certain that both the minimum menu number and the maximum menu number do NOT exceed the value of the last record in the MENUS file. The minimum and maximum menu numbers may be the same so long as the rule above is not violated. Once you have entered these values <PgDn> if necessary to return to the Main System Menu. Now access the Menu Selection screen again by choosing S - Select Utilities, then mark Change Current Menu true, then <PgDn>. The correct range of menu choices should now be displayed. Now set the value for the default menu desired and <PgDn> to return to the Main System Menu. Now SAVE this new information as part of your configuration by selecting the option * - Config Update and pressing <ENTER>. Then <PgDn>. You now are ready to test the application. <ESC>ape to DOS and restart WAMPUM in user mode. Select the A - Add Records option and make certain that the correct menu displays. Press <ESC>ape. Now choose S - Select Utilities and mark Change Current Menu true and <PgDn>. The correct range of menus should appear, and you should only be able to enter a number in the range specified. If not, restart WAMPUM in Developer Mode and change the ranges following the steps outlined above. NOTE: In all except the FoxBASE+ versions of WAMPUM, you can change menus from the Main System Menu by pressing the ALT-M hot key. 2.1.14 Building an Audit Trail File (AUDIT.DBF) For a variety of reasons, it may be desirable to create an audit trail of all data added or changed in a data base. This can be done as a means of verifying the accuracy of data posted to the data base. Or it can be done in multi-user environments to provide update integrity to the master data base while many users share access to a copy of the data base from the previous day. In the latter instance, the audit trail serves as a transaction log of new entries to the master data base. These transaction logs can be built using numerous workstations. Then at the end of the day all of the new transactions can be posted to the master data base using WAMPUM's Copy Utilities. To invoke the Audit Trail/Transaction Logging feature of WAMPUM, you must be using version 2.9 or later of the software. You must assure that some field in your data base has unique values and is indexed before implementing transaction logging. This index must be set as the PRIMARY INDEX before executing a configuration update. Then select 53 the * - Config Update option and change the Enable Audit Trail? prompt to True. Thereafter, WAMPUM will automati- cally create an AUDIT.DBF file in which it will post any changes to the current data base using the index which was the current index at the time of configuration update as the key field in the event later transaction log posting is desired. It is the developer's responsibility to assure that the AUDIT.DBF file is periodically purged since it will continue to grow indefinitely until the Enable Audit Trail prompt is turned back off by setting it false. Purging consists of deleting AUDIT.DBF and AUDIT.DBT from the current application directory with the following commands: CD \{current application directory} DEL AUDIT.* Once these files are deleted, WAMPUM will recreate them the next time WAMPUM is run in this directory. See the section of the User's Guide which addresses the COPY UTILITIES for information on posting transactions to the master data base from an audit trail file. 2.1.15 Preformatted Output (WAMPUM.DBF) 2.1.15.1 Overview WAMPUM PreFormatted Output is the feature for which many dBASE users have clamored for years. It is a tool by which a developer can "hard-code" ALL required components to generate report, label, or form letter output in advance. Stated differently, it frees the end-user from having to specify which records should be printed and in what order every time a report is run. For each new application you develop, WAMPUM will create a separate data base file, WAMPUM.DBF, which stores up to 80 preformatted reports, labels, and form letters. The end user then can call up a list of these preformatted output choices and mark the ones desired. These then are produced automatically with no further user intervention. 2.1.15.2 Building the WAMPUM.DBF File The first step in developing WAMPUM Preformatted Output is to create the WAMPUM.DBF file to store the information. This is done by selecting W - WAMPUM PreFormatted Output from the Main System Menu. When WAMPUM asks whether to create the WAMPUM file, respond with either T or Y to create the empty data base. 54 2.1.15.3 Adding To/Editing the WAMPUM File Building preformatted output is much like adding and editing data in any other .DBF file. First, pick the F - File Select option from the Main Menu, and choose WAMPUM as the name of the data base to use. When the Main System Menu returns, the bottom of the screen should show the file in use with the message: FILE: WAMPUM. To create a new entry in the file, select the A - ADD record option. To change an existing entry, select E - EDIT record. When the data entry screen appears, you will be prompted for the following items of information concerning the report, label, or form letter you wish to preformat: DATAFILE Enter the name of the primary data file which will be used in producing the output. Do NOT include the .DBF file extension. SORTINDX If you want the output sorted in a particular order, then you may specify the sort index by entering the name of index file. Do NOT enter the file extension. If this field is left blank, the output will be produced in the actual order of the records in the primary data base. RPTLBLFRM Enter either R, L, or F to tell WAMPUM whether the output will be a report (.FRM file), label (.LBL file), or form letter (.DBF file). For FoxBASE+ versions, you also may include an ampersand (&) to execute a program (.PRG or .FOX file). OUTFILE Enter the name of the actual report form, label format, or form letter file. Do NOT include the file extension. You also may enter a program name in FoxBASE+ versions. FONT Enter a number between 0 and 9 to identify which font will be used in generating the output. See the section on Printer Configurations for more information. CRITERIA Enter the selection criteria just as they would be entered in the Select Utilities option previously discussed. Note that there is one enhancement. If there is a particular range of dates you want to prompt for at execution time, then you can specify the field to which the date range will apply by surrounding that field with //'s. For example, suppose you were generating a report which would show new job applications received for a certain period of time. If the field name storing the application date was 55 APPLICDT, then the following syntax in the criteria would allow the user to enter a date range at run time for the application date: //APPLICDT//. DESCRIP Enter a brief description for the output you just designed. This is what will appear on the menu when the user selects WAMPUM Preformatted Output. RELFILE1 Enter the file name of the file to be related to the primary data base when the output is run. See the section on Z - Zoom/Relate File for more information. RELINDX1 Enter the file name of the index to be used in relating the secondary file to a field in the primary file. See Z - Zoom/Relate File for more information. Once all of the above entries have been made, a new record is stored in the WAMPUM.DBF file. When you have added all of the entries desired. Exit from WAMPUM by pressing <ESC> from the Main System Menu. Then restart WAMPUM and select the W - WAMPUM PreFormat option to try out your new output. 2.1.16 Resetting the Developer Password WAMPUM provides the capability to reset the developer password from VOODOO to some other password of your choice. This is done using the DOS ENVIRONMENT and the SET command. To reset the password, you should insert a line such as what appears below in the AUTOEXEC.BAT file in the root directory of the hard disk which will be used to boot the system. SET WAMPUM=MOVOODOO The value of the WAMPUM environment variable beginning with the THIRD character becomes the new developer password when the system is restarted. In the case outlined above, the password still would be VOODOO since the first and second characters are ignored. Note that this is anything but a secure system. What it will do is keep the casual or novice user from entering WAMPUM in developer mode accidentally. 2.1.17 Network Considerations Multi-user data base access via NETBIOS-compatible networks adds a whole new dimension to WAMPUM applications. 56 Considerations such as security, passwords, audit trails, record and file locking are but a few of the new worries you will face. The best advice for those just getting started with networks is START SMALL! A few users sharing a simple data base is the best way to get a feel for networks. WAMPUM provides a margin of security and reliable record and file locking. Because of the nature of DOS and the computers which run under DOS, WAMPUM is NOT and CANNOT take the place of the mainframe at your local department store. For many network applications, you may not need WAMPUM to impose password security. If you don't need it, DON'T use it. The hard disk documentation details the process for creating user id's. 2.1.18 Making a Backup of the User Application Once you have completed building a new application in its own subdirectory, this then can be saved using the BACKUP command for subsequent use by end-users. When the application is completed, simply type the following command substituting the name of the subdirectory in which you built the application for the word SUBDIR below. If you are using a drive other than Drive C, you would want to change the C: as well. BACKUP C:\SUBDIR\*.* A: This will make a backup copy of the application on a formatted floppy in Drive A. The end user then can take this floppy and restore it to the system on which it will be run with the command: RESTORE A: C:\*.* /S The DOS Restore command automatically will construct the new subdirectory on their disk and then copy the appli- cation without any user knowledge of file copying. 2.1.19 Writing the Documentation Perhaps the most important step in building a new application is to write some documentation explaining what the system does and how to use it. Don't distribute new applications without documentation! It gives WAMPUM and yourself a bad name. 57 2.2 ! - RUNning an External Program Assuming you have sufficient memory and except in the FoxBASE+ versions, external programs can be run from within WAMPUM using the ! - Run External Program option on the Main System Menu. The following programs can be run: executable programs in either .EXE or .COM format and DOS batch files with .BAT file extension. In addition, you can enter any DOS command and execute it with this option. You also can exit to the DOS level temporarily by entering \COMMAND.COM as the file name to run. Note, this may only work with DOS 3.0 and above. Similarly, directory paths may precede program names with DOS 3.0 or above. Any program within the DOS PATH may be run without specifying the directory path. 2.3 & - Run FoxBASE+ Commands/Programs In FoxBASE+ versions, a "simulated dot prompt" replaces the ! - Run External Program option. You still may run any external program by preceding the DOS command or program name with an exclamation point (!). This option also permits you to execute virtually any dBASE III Plus-compatible command or function. Consult any of the 400+ page reference books in your friendly bookstore or library for a summary of these commands and what they do. You also may run simple, unnested programs up to approximately 500 lines in length depending upon the amount of free memory in your computer. If you also own a FoxBASE+ compiler, compiled programs also can be executed from within this option. As a reference on programming in FoxBASE+, you may wish to obtain George Goley's Dynamics of FoxBASE+ Programming, published by Dow Jones-Irwin. This book assumes you already know virtually all dBASE commands and functions. 2.4 Z - ZOOMing or RELATing a Supplemental File WAMPUM provides the capability to link a secondary file for purposes of report, label, and form letter output. This can be done automatically within the WAMPUM Preformatted Output option, or it can be done manually using the Z - Zoom/Relate File option. There are many instances in which it is helpful to have a secondary file to provide "table lookup" of data which otherwise would have to be retyped in each record of a data base. For example, if each customer has an ACCOUNT 58 NUMBER, it would be silly to build an orders file which required the entry of the customer's name, address, and phone number every time an order was placed. Instead, the orders file could contain the customer number, and a secondary file could be used to "look up" the customer's name, address, and phone number whenever a report, label, or form letter was produced. There are four prerequisites for relating a secondary file with WAMPUM. (1) There must be an IDENTICAL field in both the main data base and the related file; (2) the key field in the related file must be indexed on that key; (3) the index file name must be identical to the name of the key field; and (4) both the related file and its index must either be in the default directory or must be accessible via the DOS PATH. To link a secondary file, pick the Z - Zoom/Relate File option on the Main System menu. Then enter the name of the secondary file and the index. When the Main System Menu reappears, the last line of the screen will show a relation is in effect with the following expression: FILE: ORDERS/R Fields in the related file may then be accessed within report and label forms as well as within form letter files using the following command syntax: ALIAS->FIELDNAME where ALIAS is the name of the related file and FIELDNAME is the field name to be output. See the example below for further clarification: CUSTOMER ORDER FILE CUSTOMER FILE (ORDERS.DBF) (ACCOUNTS.DBF) ACCTNO RELATED FIELD ---> ACCTNO (indexed) ORDERDT CUSTNAME ITEMS ADDRESS PHONE As a FIELD CONTENTS entry in the report form, you could then specify ACCOUNTS->CUSTNAME once the 59 ACCOUNTS file was related using the ACCTNO index. This would tell WAMPUM to output the actual customer name rather than the account number found in the orders file. 2.5 G - Global Replacement of Data There are occasions in which it is desirable to replace different pieces of data in a file for a large number of records in one pass rather than calling up each record individually. Be aware that the potential for disaster goes up dramatically any time you are replacing data simultaneously for more than one record! If you are new to WAMPUM and particularly to the power of dBASE III's REPLACE command, stay away from this option! This feature has been added to WAMPUM against my better judgment because of the pleas of many experienced dBASE users. If you do not need the temptation of this option, delete item 18 from the Menu # list when you configure new WAMPUM applications! G - Global Replace is a function closely akin to global search and replace on many word processing systems. It involves two steps: (1) selecting a group of records to be processed and (2) revising one or more fields of data in the records which meet the selection criteria. If you already have entered Selection Criteria, then executing G - Global Replace always works with the group of records meeting those search criteria. You must have already entered Selection Criteria before selecting G - Global Replace. You are well advised to run a list using the Select Criteria you have in mind for Global Replace to make sure the correct records have been selected. Once Global Replace has been executed, it's too late to get them back! See the Select Utilities section of the User's Guide for more details. Once record selection criteria are in effect, G - Global Replace will display the Global Replace Screen which permits you to specify up to 10 different fields which can be updated in one pass through the data base. For each field, you specify two pieces of information: (1) the field name and (2) the dBASE field expression to be executed against that piece of data. 60 In its simplest form, you may wish to replace all DUE DATES with a new value 30 days later. Assuming you already have selected the range of records to be changed, the correct procedure would be to use the <Up> or <Down> arrow to first find the DUEDT field. Once displayed, press <ENTER>. When prompted for the field expression, enter the following: DUEDT+30. Then press <ENTER>. If there is another field to be replaced, you would leave the LINK variable in the AND position and press <ENTER>. A second line would permit you to repeat the above process for another piece of information. When finished, simply press <PgDn> while the cursor is in the LINK field and the global search and replace will proceed. If you have made a mistake, press <ESC> to exit without executing the global replace! Another couple of examples may help. If a group of last names had been entered in upper and lower case and you wanted to convert them to ALL upper case, you would first specify the group of records to be processed using SELECT ASSIST. When the Global Replace Screen appears, find the LASTNAME field and press <ENTER>. For the field expression, UPPER(Lastname) should be entered. Then press the <ENTER> and <PgDn> to proceed. REMEMBER: Always RUN A LIST against your existing SELECTION CRITERIA to make certain that only the desired records will be REPLACED before executing G - Global Replace. If you're new to WAMPUM and data base management, make a full backup of your data base application before using this option! 2.6 C - Copy Utilities for Importing & Exporting Data WAMPUM's C - Copy Utilities option provides a rich variety of file importing and exporting tools permitting standard dBASE data bases to be transferred into or out of virtually any of the common file formats. In addition, a data base structure file can be created which permits simple revision of a data base structure where additional fields become desirable after an application has been built. With the exception of the dBASE III structure and audit trail options, you can narrow down which records will be copied by first specifying selection criteria using the S - Select Utilities option. 61 When the C - Copy Utilities option is selected, you initially are prompted for three pieces of information: (1) whether you will be COPYing data TO or FROM another file from the file currently in use; (2) the file type of the other file; and (3) the file name of the other file. Copying TO Another File Copying TO Another File requires that the first prompt be answered with a T. Then a file type is specified. And then the file name of the receiving file is specified. If you specify a dBASE III type data base file as the receiving file, then one will be created if the file name specified does not already exist. If it exists, you will be asked whether to Quit, Overwrite, or Append to the existing external file. If you specify COPY TO a dBASE III Structure, WAMPUM will copy the structure of the current data base into a new .DBF file with four fields: Field_Name, Field_Type, Field_Len, and Field_Dec. Each record entry in the new file will match a field in the structure of the current data base. This file then can be added to, edited, and records can be deleted. Once revised, this file then can be used as the new file structure template for transferring the current data base into a new file structure. This is covered in detail below. If you COPY TO a Standard Data Format file, WAMPUM will create a new flat file consisting of all the selected data in the current data base in ASCII format. Each record will occupy one line in the new file with a carriage return/line feed at the end of each line or record. COPYing TO a Delimited Format file permits the user to identify what character should be used to surround each character field in the new data base. For example, BASIC expects character fields in a sequential file to be delimited with QUOTES. COPYing TO an Audit Trail file is never permissible. COPYing TO an Empty dBASE III file makes a duplicate empty data base file with the same file structure as the current file in use. 62 Copying FROM Another File Copying From Another File means that you will be IMPORTING data from another file INTO the data base file currently in use. The only exception is the dBASE III Structure option covered below. To COPY FROM another file, enter F at the To/From prompt. If you COPY FROM another dBASE III data base, then the information in ALL records in that data base will be appended to the data already in the current data base. Only field data whose field names and type match exactly those of the current data base will be copied. Existing records in the current data base will not be deleted. If you COPY FROM a Standard Data Format file, its records are appended to the information, if any, which already exists in the current data base. Note that the current dBASE III file structure should be created first to match the format of the SDF file. If you don't understand this, consult a good dBASE III Primer before attempting to use this option or the next one. If you COPY FROM a Delimited file, its records are appended to the information, if any, which already exists in the current data base. Note that the current dBASE III file structure should be created first to match the format of the delimited file. See the caveat above before attempting this. COPYING FROM a dBASE III Structure is one of the ways WAMPUM can modify the structure of the current data base and move the file contents to a new dBASE III file. To modify a file's structure, follow the steps outlined above to create and revise a new dBASE III structure file. Once completed, place the original dBASE III data base file back in use with F - File Select. Then pick the COPY FROM option and specify option 2, a dBASE III Structure. Enter the name of the structure file as the external file. You then will be prompted to enter a name for a new dBASE III data base file to be built using the new structure and the data from the data base file currently in use. Enter a name of your choice. Once completed, place the new file in use and check the data to assure that it copied what you intended before deleting the old data base! Once you are certain that it looks the way it should, then reindex the file following the instructions in the I - Index Select/Create section of this User's Guide. You then may delete the original data base preferably after making a backup copy to a floppy. 63 COPYING FROM an Audit Trail file is WAMPUM's way of allowing posting from a transaction file. In addition, the developer must have set the AUDIT TRAIL flag True for this application when the G - Config Update option was run. And, the audit flag must be set to False before posting to the master data base begins. Assuming the above conditions have been met, a file will exist in the default directory named AUDIT.DBF. This should be entered as the external file name or simply enter the drive designator indicating the drive location of the AUDIT files, e.g. C: or A: with a floppy. For the transaction posting to work, the current file and lead index must match the file and lead index designated when the audit trail file was created. Otherwise, an error message will be given indicating what the required file and index must be. If no error condition is present, then WAMPUM will post all information in the audit file to the current data base and will notify the user when this has been completed. Remember that the values in the lead index must be unique or the AUDIT file will be posted to the first matching key found in the index. Note also that this function is accessible only to users with the developer password. 2.7 Deleting & Undeleting Groups of Records WAMPUM provides a means of marking a group of records as DELETED as well as a means of restoring a group of records which already have been marked for deletion. To use this function, you must: (1) Start WAMPUM with the Developer Password! (2) Specify Record Selection Criteria, and (3) Assure that the primary index in use evaluates to a character expression. If any of these three prerequisites is missing, WAMPUM ignores the attempt to delete or undelete a group of records just as if the function did not exist. Once the above prerequisites have been satisfied, you should first run a sample listing using the List File Contents option in the S - Select Utilities. This will assure that you are working with the group of records desired. Next, pick the function desired: either M - Mark Records *DEL* or U - UN*DEL* Records. When WAMPUM prompts for the entry to find, type an asterisk (*) and press <ENTER>. If 64 the prerequisites in the first paragraph have been met, WAMPUM will ask if you really want to DELETE or RESTORE the selected group of records. Type Y if you want to proceed, or press <ESC> to abort. This function provides a quick way to mark a large group of records deleted once the same group of records has been archived to a different file. When the X - Rebuild / FileFix option is then run, the group of records is deleted permanently and cannot be restored with the U - UN*DEL* Records function. Note that this function requires an active Record Selection Criteria expression to avoid the possibility of marking every record in a file as deleted. If you really want to delete all records in a file, specify the following Record Selection Criteria: RECNO() >= 1. This means all records. 2.8 Reserved Variables, FoxBASE & Clipper Functions 2.8.1 Overview In addition to a number of reserved functions provided in the standard implementation of the dBASE III programming language, WAMPUM adds all Clipper enhancements (except in the FoxBASE+ versions) plus some new functions of its own. This section is designed to bring you up to speed on these new functions and some of the major dBASE III commands and functions. It is by no means an exhaustive treatment of all dBASE III Plus functions. Consult any of the dBASE III reference books in your local bookstore for more information on dBASE III commands and functions. 2.8.2 CHARACTER/STRING functions Character string manipulation becomes critical in producing meaningful reports and form letters. WAMPUM provides a rich assortment of functions to assist the developer. As is true of all functions, each contains a keyword followed by parentheses, one or more arguments separated by commas, and closing parentheses. AT(exp1,exp2) allows a search of the second string expression for the first occurrence of the first expression. A numeric value is returned for the character position of the first match. For example, AT("son","Thompson") would return 6. If no match was found, a 0 would be returned. 65 CHR(n) returns an ASCII character represented by ASCII code n. For example, CHR(27) is the escape code. SPACE(n) allows the generation of n spaces where n is a numeric value. For example SPACE(5) produces 5 spaces. STR(exp1,n,dec) converts a numeric expression (exp1)into a string expression n characters long with dec decimals. For example, STR(153.123,5,1) would yield "153.1". SUBSTR(exp1,n,len) permits extraction of a portion of a string from a larger string. n is a numeric specifying the starting position in the exp1 string. len is a numeric specifying the number of characters to extract from the starting position. For example, SUBSTR("Thompson",3,2) would return "om" which is 2 characters beginning at character position 3. TRIM(exp1) tells WAMPUM to trim off trailing spaces from a character string. For example, if a 30 character NAME field contained "John Jones " then TRIM(NAME) would yield "John Jones" with no trailing spaces. UPPER(exp1) converts a string expression to all UPPERCASE. LOWER(exp1) does just the opposite. VAL(exp1) returns a numeric value for the exp1 string. For example, VAL("02345") would return the integer 2345. 2.8.3 DATE functions WAMPUM supports the dBASE III function for today's date which is DATE() as well as the reserved word TODAY which also is today's date in date format. DTOC(DATE()) would convert today's date to a character string in the format 06/12/86. The converse also works to convert a string to a date: CTOD("06/12/86") would convert the string to a date variable. Several DAY functions are available including: CDOW() which outputs the actual day of the week such as Monday; DAY() which produces a numeric representing the day of the month such as 31; DOW() which produces a numeric representing the day of the week such as 5. Note that an empty date field always produces DOW equal to 0. This is a good way to test for blank dates. 66 Several MONTH functions also are available: MONTH() outputs a numeric representing the month of the year such as 2; CMONTH() generates the actual name of the month such as February; YEAR() outputs a 4-digit numeric value representing the year such as 1987. Clipper provides a date-to-string conversion function with the DTOS() command. The syntax is DTOS(FILINGDT). Assuming a filing date of 10/10/85, DTOS(FILINGDT) would output the string "19851010". This function is particularly helpful in building indexes where a date field is converted to a string, but a developer wishes to preserve proper ordering of dates. DTOC(FILINGDT,1) is the FoxBASE+ equivalent. In producing reports and labels, you can reformat a date field into a standard date character string using the WAMPUM function FULLDATE(). FullDate(FilingDt) is the syntax assuming that filing date was a date field in your data base. If the date were 10/20/85, FULLDATE(FILINGDT) would output October 20, 1985. In some applications, it may be desirable to roll a date over to Monday if it hits on a weekend. WAMPUM's WEEKDAY() function does this. Assuming a filing date of 06/14/86 hits on a Saturday, WEEKDAY(FILINGDT) would return a date expression with a value of 06/16/86 which is the following Monday. Note that this function could be combined with a previous one to produce a standard text date: FULLDATE(WEEKDAY(FILINGDT)). 2.8.4 DUPKEY("FIELDNAME") When building the EDIT.DBF edit checks, many appli- cations require the ability to test whether the key field of the record being added to a data base already exists and, if so, to return an error. This is critical if you will be using the AUDIT TRAIL function. The DUPKEY() function provides this capability. In order to use it, the following conditions must be met: (1) The key field to be checked must be indexed; (2) That index must be the primary (first) index in use when the file is ADDed to or EDITed; 67 (3) The name of the key field must be specified in parentheses and quotation marks as an edit check in the EDIT.DBF file. The syntax is shown in the following example using PARTNO as the name of the indexed key field which is to be checked: DUPKEY("PARTNO") 2.8.5 EMPTY(fieldname) tests for empty fields EMPTY(FieldName) returns a logical True if a character, memo, or date field is empty, or if a numeric field is 0, or if a logical field is False. Otherwise, a logical False is returned. This function does not work reliably in FoxBASE+. 2.8.6 LASTTIME field in data bases If LASTTIME is included as a Character-type field in any data base, WAMPUM will automatically post the current time to this field whenever a record is ADDed or EDITed in that data base. This provides a convenient method of determining when records were last updated with no user control over the field contents. 2.8.7 LASTUPDT field in data bases If LASTUPDT is included as a Date-type field in any data base, WAMPUM will automatically post the current date to this field whenever a record is ADDed or EDITed in that data base. As with LASTTIME, there is no user control over this field's contents. 2.8.8 LASTUSER field in data bases If LASTUSER is included as a Character-type field in any data base, WAMPUM will automatically post the current USERID to this field whenever a record is ADDed or EDITed in that data base if the SET USERID=X line has been added to the AUTOEXEC.BAT file for each network user. This provides a convenient method of determining who fouled up what with no user control over the field contents. Please note that before using the SET USERID=X command, you must first create a USERS data base and index with the names and passwords of those authorized access. 68 2.9 PATH Considerations Whenever WAMPUM is started, part of its initialization process includes reading the DOS PATH which then becomes WAMPUM's PATH as well. For this reason, developers need to be careful NOT to build WAMPUM applications in a directory which is part of the DOS PATH since all of the files in this directory then would be accessed by other WAMPUM applications. The only exception to this guideline might be in situations in which a related file and its index need to be shared with several different applications. In this case, just the related file and index should be placed in a directory supported by the DOS PATH command, NOT the configuration files for the WAMPUM application itself. If you don't understand this exception, don't use it. 2.10 Enabling USERID's and Passwords WAMPUM now may be configured to require those accessing files through WAMPUM to log in with a USERID and PASSWORD. Typically this would be used for network applications if the network itself does not provide adequate protection. The USERID-PASSWORD system also may be invoked in single-user applications. Step 1 to force use of the USERID-PASSWORD system is to create a data base which will store the user names and passwords of those authorized to utilize WAMPUM. Create a new subdirectory on your hard disk and run WAMPUM in Developer Mode. Then Build A New File and name it USERS. Two fields must be created in this file structure. Two additional fields are optional. The two mandatory fields are USER and PASSWORD. Both fields must be Character-type fields with a field length of 8. The optional fields are SUPERVISOR, which must be a Logical field of length 1, and CONFIG, which must be a character field of length 7. Once you have built the new data base, use F - File Select to place the USERS file in use. Then use I - Index Select/Create to build an index on the USER field. You then are ready to ADD records to the data base for each anticipated user. For each user, you must include a user name and password. These entries ALL must be in UPPER case letters! Once you have added all the entries desired, exit to the DOS level and copy USERS.DBF and USER.NTX into a directory 69 which is part of the DOS path. This will enable WAMPUM to find the files whenever an attempt is made to run WAMPUM. Assuming your \DOS subdirectory is part of the path, a simple command to copy the files would be as follows: COPY USER*.* \DOS Whenever you wish to add new users, move to the directory in which you established the original copy of the file (NOT the directory which is part of the DOS PATH!). Add whatever new entries are desired, and then copy the files again to the same directory sharing the DOS PATH which was used previously. If you accidentally get tangled up to the point that you can no longer get into WAMPUM, turn OFF the password feature by disabling the USERID variable in the environment. To do this, exit to DOS and type the following command at the DOS prompt: SET USERID= If the SUPERVISOR field is used and is marked True for a given user, then WAMPUM automatically will be started in Developer mode for that user. This means that all 21 menu options will be available to this user. If the CONFIG field is used, then the developer may specify a configuration file for use by each user. This configuration file takes the place of WAMPUM.MEM which will be used unless the CONFIG field is used and has an entry. The process for generating these individual configurations is quite simple. Create a new WAMPUM configuration as you normally would using the * - Config Update option. Then exit to DOS and copy WAMPUM.MEM which was created to a new filename matching the CONFIG field value. Make certain that the file extension remains .MEM. Then edit the USERS data base and add an appropriate CONFIG file name for the users desired. For example, let's assume there is a USER named Jones. We want that user's CONFIG file to be named JONES.MEM. Run WAMPUM in Developer Mode and configure the application in the normal manner. Now exit to DOS and type: COPY WAMPUM.MEM JONES.MEM Revise Jones' entry in the USERS data base to reflect a CONFIG field value of JONES. 2.11 WAMPUM & DOS System Errors WAMPUM System Errors are error conditions caused by one of three conditions: 70 (1) a DOS-error is detected, (2) a Clipper or FoxBASE+ error is detected, or (3) the abort key (ALT-C) in Clipper versions is pressed by the user. In any of these three situations, a system error message appears on the top line of the screen followed by a prompt telling you how to proceed. What follows is a brief description of what to do in each of these error situations. DOS errors typically are caused by a hardware failure such as a bad hard disk, a missing floppy disk in Drive A, or an out of memory condition. With any DOS error, you should always terminate the program if given the option to do so. This will gracefully close all open data bases and indexes and assure that no permanent damage is done to your data. Clipper or FoxBASE+ errors typically occur when WAMPUM encounters an illegal dBASE expression in a report or label form, in macro expressions or edit checks, or in a record selection specification. For example, if you entered LASTNAME=Jones as a record selection criteria without surrounding Jones in quotes, a system error would occur whenever you executed a report, label, form letter, or listing of the file. Unfortunately, the current version of the Clipper compiler, with which WAMPUM was produced, provides no means for WAMPUM to test such expressions for validity before executing them. The FoxBASE+ versions of WAMPUM will catch these errors. However, once Clipper attempts to execute an invalid expression, a system error occurs. You typically will be returned to the Main System Menu when these errors occur. You then can revise the offending code and try again. In the case of invalid expressions, you usually can opt to ignore these error so long as you understand that the results of any output may be erroneous. There may be occasions when you want to cancel some WAMPUM session usually because a report listing is not producing the results desired and you do not want to waste 100 sheets of paper. Press <ESC>ape and the output will be terminated when the next qualifying record is reached. Do NOT press CTRL-ALT-DEL to terminate WAMPUM. This may permanently damage any data bases in use at the time. 71 3 End-User Functions 3.1 Overview The developer's section explained the step-by-step process for building a new application. This section is designed to acquaint the end-user with information necessary to build and maintain an existing data base application as well as how to extract information from an existing file. End-users typically want to do two things with a data base. They want to add or change information in an existing file (INPUT functions), and they want to extract information from an existing file (OUTPUT functions). In WAMPUM, INPUT consists of ADDing new records, EDITing existing records, and DELETing or UNDELETing existing records. For network applications, only one person can edit any individual record at any given time. Multiple people may be adding new records at the same time. And multiple people may be editing different existing records. In WAMPUM, OUTPUT means you just want to look at or print something which already exists in the file. For network users, multiple people can be outputting information from the same file simultaneously. ALL output falls into one of two categories: single record or multiple record output. Single record OUTPUT is quick because it typically involves retrieval of a single record by an indexed key. This output may consist of either DISPLAYing an individual record or PRINTing an individual record. In either case, the end-user is prompted for the key of the record to find, and WAMPUM will find it in less than a second even with extremely large data bases. The record is displayed or printed in its entirety just as the information is stored. Multiple record OUTPUT tends to be slower but more useful. It is slower because WAMPUM must make a complete pass through the data base to find the records desired for output. It tends to be more useful because the output typically is formatted in such a way that the extracted data is more meaningful. Multiple record output ALWAYS involves three steps: (1) picking the lead index to specify the order in which the records will appear in the output, e.g. alphabetically, by date, or by part number; (2) selecting (i.e. narrowing down) the group of records which should be output using Boolean logic, e.g. find all the new accounts for January or just the new accounts with sales over $1,000,000; and (3) choosing the type of output desired: a list, report, mailing labels, or a form letter. Billing statements, an overdue notice, or monthly 72 summary of accounts all are examples of multiple record output which easily can be produced using WAMPUM. You must master the above concepts before use of any data base management system can be of much value. If you don't understand the relationship between input and output and the various types of output, put this User's Guide aside and try reading this section again tomorrow. 3.2 A - ADDing New Records To add new records to any data base, that file must first be selected. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only, i.e. password required. If the file you wish to work with is selected, then you should also consider whether there are indexes which you want automatically updated as you ADD new records to the file. If so, then these, too, must be selected before you ADD new records. You can determine which indexes are in use by looking at the bottom of the Main System Menu screen. New indexes can be created and/or opened using the I - Index Sel/Create option in developer mode only. Once you are working with the correct file and indexes, then ADDing records is as simple as highlighting the A - Add a New Record option and pressing <ENTER>. Or you may simply type an A while the Main System Menu is displayed. The screen will clear and WAMPUM will display a data entry screen with all of the fields in the current file. It will indicate the proposed new record number of this entry at the top of the form. Type in the data you wish to enter for each field using the UP and DOWN cursor keys to move from field to field. If a file has a substantial number of fields, then all of the fields may not fit on one data entry screen. In this case, the word *MORE* will appear in the bottom right corner of the screen. When you complete entry of data on the first screen, then a second screen with the remaining fields will appear. Saving a new entry to the file can be accomplished in several ways. (1) Pressing <ENTER> while the cursor is positioned in the last field of the last data entry screen will save the record. 73 (2) Completely filling the last field with text also will save the record. (3) Pressing CTRL-W will save the new record without displaying the remaining data entry screens if the record requires more than one screen for data entry. (4) Pressing <PgDn> in the last data entry screen of a record will also SAVE the record. Aborting a new entry can be accomplished by pressing the <ESC>ape key at any time before any of the SAVE methods outlined above occur. <PgUp> also aborts data entry in ADD mode only. WAMPUM supports updating of Memo fields in a slightly different way than dBASE III. If you wish to display or edit a memo field, then first move the cursor to that field. It will be displayed on the screen with the field name followed by *MEMO*. Note that memo fields in WAMPUM appear to be logical fields which can accept True, False, Yes, or No as entries. If you wish to edit the memo field, simply set the logical field to True or Yes by entering a T or Y. When you complete entry of data for this record and execute a SAVE using one of the methods outlined above, the Memo editor will display any memo field marked True and allow you to update it as desired. You then can either SAVE the updated Memo text by pressing Ctrl-W or ABORT the update and leave the Memo text as it was by pressing <ESC>ape. After you ADD a new entry to the file, WAMPUM will display another blank data entry screen thereby allowing you to add another entry. If you do not wish to add another entry, press <ESC>ape to exit to the Main System Menu. 3.3 E - EDITing Records To edit records in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only. If the file you wish to work with is selected, then you should also consider whether there are indexes which you want automatically updated as you EDIT records in the file. If so, then these, too, must be selected before you EDIT any records. You can determine which indexes are in use by looking at the bottom of the Main System Menu screen. New 74 indexes can be created and/or opened using the I - Index Sel/Create option in developer mode only. Once you are working with the correct file and indexes, then EDITing records is as simple as highlighting the E - Edit Record option and pressing <ENTER>. Or you may simply type an E while the Main System Menu is displayed. If you are not using indexes in conjunction with the file being edited, then you will be prompted for the record number of the record you wish to edit. Simply type in the number desired and press the <ENTER> key. If you are using one or more indexes in conjunction with the file being edited, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities for information on how to change the lead index. The simplest way in all versions except FoxBASE+ is to press ALT-I and highlight the desired index. When editing with an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. With character fields, you may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. With other types of fields, you must enter the exact key to find. Note that capitalization is critical in finding matches. If a LASTNAME field in your data base contains an entry of SMITH and you enter Smith as the key, then WAMPUM will not find SMITH. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first data entry screen displayed is not the Smith desired, then <PgDn> until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, then you may have to <PgDn> several times just to move to the next record. There currently is no key which can be pressed to SKIP to the next record without first displaying all of the edit screens for the current record. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. Once the record is displayed, move to the fields to be edited using the UP and DOWN cursor keys. You can change existing data for a field in several ways: 75 (1) You may type over the existing data. (2) Or you may delete the existing data by pressing CTRL-Y and then type in the new data. (3) Or you may INSERT new data into a field by positioning the cursor where you want the insert to begin. Press the <INS>ert key and type the new text. With multi-screen records, you can move forward to the next screen by pressing <PgDn>. You cannot move backward within a record by pressing <PgUp>. <PgUp> will save the record and move you to the previous record in the data base. The only exception is FoxBASE+ custom format files which are discussed in the Developer's Section of this Guide. CTRL-W saves the current record and prompts you for the next record to find. <PgDn> saves the current record and then displays the next record in the file for editing. You can abort any EDIT by pressing <ESC>ape before any of the SAVE actions outlined above occur. 3.4 D - DISPLAYing Records To display records in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, follow the process outlined under Edit Records to choose a file and any indexes. Once you are working with the correct file and index, then DISPLAYing records is as simple as highlighting the D - Display Record option and pressing <ENTER>. Or you may simply type a D while the Main System Menu is displayed. If you are not using indexes in conjunction with the file being displayed, then you will be prompted for the record number of the record you wish to display. Simply type in the number desired and press the <ENTER> key. If you are using an index in conjunction with the file being displayed, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities or press ALT-I in non-FoxBASE+ versions. When retrieving with an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM 76 will search for a match on the portion of the key entered. Capitalization is critical in finding matches. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first data entry screen displayed is not the Smith desired, then <PgDn> until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, then each time you press <PgDn>, WAMPUM will skip to the next record. It will NOT display the subsequent fields of the current record as is the case in EDIT mode. If you wish to look at the subsequent fields of the current record, then press the <ENTER> key rather than <PgDn>. In addition, if there are MEMO fields in the data base with which you are working, these fields will show T if there is data in the field except in FoxBASE+ versions which always show F. Empty memo fields always display F. To display the first screen of information in any MEMO field, just press <RETURN> rather than <PgDn> on the last screen of the display of the standard fields. The entire contents of a MEMO field can be displayed in non-FoxBASE+ versions by using the cursor control keys. In FoxBASE+ versions, only the first screen is shown. Use Edit mode to see the rest. If you skip past the record desired, you can also move backwards through the file in the order of the current key by pressing the <PgUp> key at any time. You can abort any DISPLAY by pressing <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep and prompt for another record to find. When you have displayed all the records desired, press <ESC>ape to exit to the Main System Menu. 3.5 M - MARKing a Record for Deletion To mark records as deleted in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode. If the file you wish to work with is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you choose DELETE. 77 Once you are working with the correct file and index, then marking records DELETED is as simple as highlighting the M - Mark Record *DEL* option and pressing <ENTER>. Or you may simply type an M from the Main System Menu. If you are not using indexes in conjunction with the file, then you will be prompted for the record number of the record you wish to mark deleted. Simply type in the number desired and press the <ENTER> key. If you are using an index in conjunction with the file, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, change the lead index and then proceed. When using an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first entry displayed is not the Smith desired, then <PgDn> through the records until the correct record is displayed. If you are using a data base with too many fields to fit on one screen, note that WAMPUM will only display the first screen of data for each record while in DELETE mode. If you skip past the record desired, you can back up through the file in the order of the current key by pressing the <PgUp> key at any time. Once you find the record you wish to mark DELETED, then answer the DELETE prompt by entering a T for True or Y for Yes, and the record will be marked deleted. You can abort any search by pressing <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep and prompt for another record to find. When you have deleted all the records desired, press <ESC>ape to exit to the Main System Menu. NOTE: WAMPUM uses the same conventions as dBASE insofar as deleted records are concerned. Deleted records are not really deleted. They are simply marked with an asterisk 78 (*) in the first record position which signifies that they will be deleted the next time the file is rebuilt using the X - REBUILD/FileFix option. At any time before you rebuild the file, any record marked as deleted can be restored using U - UN*DEL* records. The primary significance of marking records for deletion is that they will not ordinarily print when output is produced. 3.6 U - UNDELETing a Record To undelete records marked as deleted in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using F - File Select in developer mode only. If the file you wish to work with is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you attempt to UNDELETE any records. Once you are working with the correct file and index, then marking records UNDELETED is as simple as highlighting the U - UN*DEL* Records option and pressing <ENTER>. Or you may simply type U from the Main Menu. If you are not using indexes in conjunction with the file, then you will be prompted for the record number of the record you wish to undelete. Simply type in the number desired and press the <ENTER> key. If you are using an index in conjunction with the file, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index desired for record retrieval, change the lead index before proceeding. When using an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. If you are using a data base with too many fields to fit on one screen, note that WAMPUM will only display the first screen of data for each record while in UNDELETE mode. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. 79 Once you find the record you wish to UNDELETE, then answer the restore prompt by entering a T for True or Y for Yes, and the record will be restored to the data base as an active record. You can abort any search by pressing <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep and prompt for another record to find. When you have undeleted all the records desired, press <ESC>ape to exit to the Main System Menu. NOTE: WAMPUM can only undelete records which are marked deleted. It cannot recover records which have been permanently deleted using the X - REBUILD/FileFix option. At any time before you rebuild the file, any record marked as deleted can be restored using U - UN*DEL* records. The down side of this is that once the X option has been run on a file, you can no longer UNDELETE records marked for deletion since they have been permanently deleted from the data base. 3.7 P - PRINTing Records To print individual records from any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use has already been selected. If not, it can be selected using the F - File Select option in developer mode only. Also make certain that WAMPUM is configured to match the printer you currently are using. This can be changed by selecting the # - PRINTER Config option in developer mode only. If no printer has been selected, WAMPUM will print in generic mode, meaning it outputs pure ASCII text. Once the file desired is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you PRINT any records. Once you are working with the correct file and index, then PRINTing records is as simple as highlighting the P - Print Record(s) option and pressing <ENTER>. Or you may simply type a P while the Main System Menu is displayed. If you are not using indexes in conjunction with the file, then you will be prompted for the record number of the record you wish to retrieve. Simply type in the number desired and press the <ENTER> key. 80 If you are using an index in conjunction with the file, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, then change the lead index and proceed. When printing records with index retrieval, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. If you are using a data base with too many fields to fit on one screen, then only as many fields as will fit on a single screen will be displayed. To get a print out of the entire record displayed plus the contents of any MEMO fields, answer the Print Record? prompt by typing a T or Y. Make certain that your printer is turned ON and is ON LINE. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. You can abort a PRINT records session by pressing the <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep and prompt for another record to find. When you have printed all the records desired, press <ESC>ape to exit to the Main System Menu. 3.8 X - REBUILD/FileFix Computers are very temperamental when it comes to electricity. Power fluctuations will cause all sorts of undesired results when working with any data base. In network environments, power is even more critical. WAMPUM provides the X - REBUILD/FileFix option as a tool to assist in rebuilding data bases and indexes which typically have been corrupted by power problems. This option obviously does not take the place of a reliable source of electricity. If you are having to use this option frequently, then you should seriously consider an uninterruptible power supply if you value your data! This option now provides three features to assist in file maintenance: (1) data base file packing which automatically rebuilds active indexes as well, (2) memo file packing which compresses free-form text entered into memo fields, and 81 (3) reindexing which rebuilds index files associated with a data base. The file packing option (1) rebuilds the entire data base file and resets the end-of-file pointer which oftentimes is damaged by a power outage. If there are active indexes, these are reindexed as well. Be forewarned that this option automatically and permanently DELETES any records marked for deletion. Make certain that you have UNDELETED any records you wish to preserve before executing this option! Memo file packing (2) is NOT included in the dBASE file packing algorithm hence packing a data base file does not affect the memo file at all. For those new to the world of dBASE, you should be aware that any time a data base is created which includes one or more memo fields, a separate file automatically is created to store the contents of these fields. It has the same file name as the main data base; however, the file extension is .DBT. As you add data to memo fields, the actual text is stored in the .DBT file while a pointer (an address) is stored in the actual data base file. Virtually any time a memo field is revised and expanded even slightly, the entire contents of that memo field is rewritten to the end of the .DBT file, and the pointer is adjusted accordingly. Over time, the size of the .DBT file grows geometrically depending upon how often your memo fields are revised. Previous copies of memo fields are never deleted from the .DBT file. They merely occupy space. To delete them, you must actually execute a dBASE COPY of the data base and then rename the file back to the original name. WAMPUM's memo file packing option does this for you automatically. Before executing this option, always make a backup of your original data base including the .DBT memo file. Also make certain that your default drive has adequate space to house a temporary duplicate of both the .DBF and .DBT files which will be copied and then renamed! Reindexing (3) is a tool which oftentimes will cure damage from power problems without actually rebuilding the data base itself. The principal advantage to reindexing rather than file packing is that it does not delete records marked for deletion in the main data base. If this is a concern, you may wish to try this option to repair damage before choosing file packing. If you do select file packing, reindexing is performed without selecting this option. 82 3.9 S - SELECT Utilities 3.9.1 Overview The S - Select Utilities option in WAMPUM provides end- user access to the two most critical elements in extracting data from a data base: record selection and sorting. Sorting in WAMPUM is handled through changing the lead index. The Select Utilities option also provides the means for setting the primary index for record retrieval purposes. Four other dBASE III functions are provided through the Select Utilities option: (1) LIST FILE CONTENTS, to generate quick report listings with up to 9 fields; (2) CHANGE DATA ENTRY MENUS, which allows a user to select from up to 10 different data entry menus; (3) BROWSE MODE, to scan through a group of records; and (4) LIST STRUCTURE, which displays or prints a listing of a file's field structure. No User's Guide can do justice to the topic of Boolean logic which is the record selection step in both WAMPUM and dBASE III. There are numerous books including a number of dBASE III primers which cover record selection in much more detail than what is addressed here. Many are available without charge through your public library. For anyone to get the most out of WAMPUM, you must master record selection since it is the critical element in identifying which records should and should not be extracted for reports, labels, and form letters. 3.9.2 Record Selection Criteria Record Selection, which in dBASE is technically known as a filter, is the process by which you tell the computer which records should and should not be extracted in producing reports, labels, and form letters. With the exception of logical fields, the syntax for record selection typically is FIELDNAME relational operator VALUE. The syntax for logical fields is simpler. Assuming a logical field exists in your data base called MARRIED, if you want to find all the records in which the MARRIED field is True, the Boolean expression is simply the field name itself: 83 MARRIED. If you want to find all those in which the MARRIED field is False, the correct expression is .NOT. MARRIED. Any record selection expression can be linked to another expression with one of two connectors: .AND. or .OR. The other cardinal rule is that expressions on both sides of the relational operator must be of the same type. Thus, if a field is a character field then the value must be a character string. If the field is a date field, then the value must be a date. Finally, except in FoxBASE+ versions, memo fields can be searched for matches using record selection and should be treated as if they were character fields, i.e. enclose search values in quotes just like a character string! Whenever you run a report, label, or form letter, WAMPUM always checks to see if Record Selection Criteria are in effect. The bottom line of the Main System Menu also will tell you whether search criteria are active by displaying *SEL* after the file in use. If so, WAMPUM scans the data base for records whose field entries are TRUE when evaluated against the complete Record Selection Criteria. WAMPUM currently supports eight relational operators: OPERATOR MEANING = Equals; matches; begins with. <> Not equals. > Greater than; more than. >= Greater than or equal; at least. < Less than. <= Less than or equal; at most. $ Is contained in. .NOT. $ Is not contained in. The best way to master record selection is by reviewing some examples and finding one that closely matches what you want to do. For this purpose, let us assume that you are working with a data base with the following file structure: FIELD NAME TYPE LENGTH DEC LASTNAME C 20 0 ACCTNO N 5 0 ENTRYDT D 8 0 MARRIED L 1 0 COMMENTS M 10 0 Now let us assume that there are three records in the file with the following values: 84 FIELD NAME REC #1 REC #2 REC #3 LASTNAME Mundy Johns Johnston ACCTNO 12345 1234 123 ENTRYDT 10/01/85 10/31/85 11/01/85 MARRIED .T. .F. .F. COMMENTS Memo Memo Memo What follows are a number of examples showing the correct record selection syntax, what the expression means in plain English, and which records would be selected by the expression. Criteria: LAST NAME = Johns English: Find all entries where the last name is Johns. Selected: No records. Comments: Not only will no records be selected but WAMPUM will display a System Error forcing termination of the program by typing Q. FIELD NAMES are words of art which must be spelled exactly as they appear in the data base structure. While LAST NAME is fine for English, WAMPUM doesn't know LAST NAME from the MOON. The correct field name is LASTNAME with no spaces! Since LASTNAME is a character field, the value also must be a character string which means it must be enclosed in quotation marks. Either error would have triggered a System Error. Currently, there is no way to check for correct syntax before you actually run a report, label, or form letter. Then it's too late! Criteria: LASTNAME="Johns" English: Find all LASTNAMEs of Johns. Selected: Records 2 and 3. Comments: Note that EQUALS is not pure equivalency in WAMPUM, but more accurately means "begins with." If you want exact equivalence, fill out the field with enough spaces to assure that the match will force equivalence, e.g. LASTNAME="Johns " would select only Record 2. Criteria: LASTNAME="Johns" .AND. ACCTNO=123 English: Find all entries where LASTNAME begins with Johns AND the account number is 123. Selected: Record 3. 85 Comments: For every rule, there is an exception. Equals means exactly equals with numeric fields. Here the account number is numeric while the LASTNAME field is not. Note that BOTH expressions must be true for a record to qualify since the expressions are joined with .AND. Note also that the character string value must be in quotes to match the character field LASTNAME while the numeric value is NOT in quotes to match the numeric field ACCTNO. Criteria: LASTNAME="Mundy" .AND. LASTNAME="Johns" English: Find all entries where LASTNAME is Mundy and Johns. Selected: No records. Comments: Pure English will sometimes get you into trouble. A common beginner's mistake is to mix up .AND. and .OR. Remember: .AND. means BOTH expressions must be True. .OR. means if EITHER is True. Here, no one has a LASTNAME of Mundy AND Johns. All entries have a LASTNAME of Mundy OR Johns. Criteria: MARRIED .OR. LASTNAME="Johns " English: Find all entries where person is married or LASTNAME is equal to Johns. Selected: Records 1 and 2. Comments: When expressions are joined by .OR. then if either expression is true, the record qualifies. Thus, record 1 qualified because the MARRIED field is True and record 2 qualified because of the LASTNAME match. Criteria: .NOT. MARRIED .AND. ENTRYDT >= CTOD("10/31/86") English: Find all the unmarried people with an entry date of at least October 31, 1986. Selected: Records 2 and 3. Comments: The connecter is .AND. so both expressions must be true. Since the MARRIED field is false in both record 2 and 3 and since the ENTRYDT is at least 10/31/86, they both would be output. Note that the VALUE type must match the field type with the DATE field. There is no direct way to 86 enter a date in dBASE. Thus, you must enter the character string "10/31/86" and then convert it to a DATE with the character-to-date function: CTOD(). Criteria: ENTRYDT >= CTOD("10/01/86") .AND. ENTRYDT <= CTOD("10/31/86") English: Find all of the October, 1986 entries. Selected: Records 1 and 2. Comments: Here we are using a range of dates to select a month's worth of entries. Note that spacing between text is optional. Both expressions must be true for a match. DATE fields must have DATE values. CTOD() does it. Criteria: "This is a test"$COMMENTS English: Find every record in which the text "This is a test" appears in the COMMENTS memo field. Selected: Don't know. See below. Comments: The $ operator is one of Boolean logic's most powerful tools since it automatically searches TEXT STRINGS for a match anywhere in the string. It can be especially helpful for use with fields in which a word may appear at any place in a lengthy string of text. For purposes of searches, MEMO fields are treated by WAMPUM as text strings. Thus, you can search ANY memo field with the logic outlined above except in FoxBASE+ versions. To negate the expression, i.e. "This is a test" is NOT contained in the MEMO field, the correct syntax is .NOT."This is a test"$COMMENTS. In this case, we didn't specify the contents of the MEMO field in developing the example. Thus, there is no way to tell if the text was found or not. WAMPUM'S SELECT ASSIST For those experiencing problems in mastering dBASE Boolean syntax but who have mastered Boolean selection theory, WAMPUM provides a helping hand: SELECT ASSIST. By entering an asterisk (*) as the first character in the Record Selection field or whenever you pick the LIST FILE CONTENTS option when no selection criteria are in effect, SELECT ASSIST is activated. Or press the ALT-I hot-key. 87 SELECT ASSIST is a menu-driven record selection tool similar to that found in many data base systems such as dBASE III Plus. It permits a user to enter up to 10 record selection criteria using a 4-step menu process. As indicated earlier, it cannot replace the human brain in figuring out which records you want to work with, but it can help you master record selection syntax. FIELDNAME SELECTION Once SELECT ASSIST is started, it will display a screen with the name of the first field in the active data base. Step 1 is to identify the field involved in making your selection of records. If you don't remember the field names in the data base, simply press the <Dn> and <Up> cursor keys to "thumb through" the field names. When you find the one you want, press <ENTER>. If you already know the field name and there are a lot of them in your database, you may find it more convenient just to type several of the beginning characters of the field name. SELECT ASSIST will begin searching for a matching field name as soon as you type a letter between A and Z. If it finds no match, it will beep and redisplay the first field name in the data base. Since several fields obviously can have the same beginning letters, you may have to type several letters of the field name for SELECT ASSIST to find the field you're looking for. Once the field name appears that you want, press <ENTER> to continue. RELATIONAL OPERATOR SELECTION After selecting a field name, you then must choose a relational operator telling WAMPUM what sort of comparison you wish to make against this field. The default is EQUALS. You may "thumb through" the choices by pressing the <Dn> or <Up> cursor keys. Depending upon the field type of the field name specified, the relational operator selections will vary. Display the operator desired, then press <ENTER>. VALUE SPECIFICATION Once you have specified the relational operator, you next must tell SELECT ASSIST what VALUE for this field you want to find. Again, depending upon the field type, your options in specifying a value may be limited. For example, if the field is a date field, the VALUE must also be a date. With a logical 88 field, there is no value specification. Character fields require the entry of text without surrounding quotation marks. Press the <ENTER> key once you have specified the value desired. CONNECTOR SELECTION Connector selection allows you to indicate how this selection should be linked to the next selection, if any. The choices are listed by using the <Dn> and <Up> cursor keys. You may choose AND, OR, or NO CONNECTOR. If you choose NO CONNECTOR, SELECT ASSIST assumes you are finished. Specifying either of the other choices by pressing <ENTER> takes you to the next line to enter a second selection criteria beginning with another field name. Once you have entered all of the selection criteria desired, press the <PgDn> key in the CONNECTOR SELECTION field to tell SELECT ASSIST you are finished. You may also specify NO CONNECTOR and press <ENTER> which has the same effect. If you accidentally press <ENTER> to move to the next line with a connector of AND or OR, you may still end processing of SELECT ASSIST by pressing the <PgDn> key in the FIELD NAME position. In this case, SELECT ASSIST assumes you wanted to use only those selection criteria on the lines above the current line. 3.9.3 Listing File Contents Many times there is a need to produce a so-called "quick and dirty" report which lists certain fields of information on a group of records in the data base. The List File Contents option in conjunction with a previously specified Record Selection Criteria satisfies this need by simulating the dBASE LIST command. If the List File Contents option is marked True, WAMPUM first will display the SELECT ASSISTANT previously described if no record selection criteria are in effect. After specifying record selection criteria, WAMPUM then will display a screen asking the user to identify the fields to be listed. The user should type a number between 1 and 9 beside each field which should be listed. No number can be used twice! If a MEMO field is to be included in the listing, it should be the field with either the highest or lowest number to assure that it prints in either the far right column or the far left column of the listing. Pressing <PgDn> moves the user to a screen which prompts for (1) whether to print the listing, (2) whether to output all records (i.e., override record selection criteria then in effect), and (3) whether to output records marked for 89 deletion. When these prompts are answered, WAMPUM will produce the list with field headings either on the screen or on the printer. If the total width of the fields specified for the listing exceeds the screen width or current printer width, the listing will be wrapped to the next line. At the end of the listing a summary of record selection criteria displays. 3.9.4 Changing Current Data Entry Menu In addition to its standard data entry menu, WAMPUM provides the capacity for creating up to 9 customized data entry menus to match different data entry stages for any given application. The number of menus available to the end- user is specified by the developer. You may change data entry menus at any time by following these simple steps. Access the S - Select Utilities screen from the Main System Menu. Change the Change Current Menu field to T and press <PgDn>. A listing of the available menus will be displayed. Simply type the number corresponding to the menu you want to use. You then will be returned to the Main System Menu. Until you change menus again, this new data entry menu will appear whenever you Add, Edit, or Display Records. Except in FoxBASE+ versions, you also may change menus from the Main Menu by pressing the ALT-M hot key and choosing a new menu. 3.9.5 Picking the Lead Index Files can only be accessed and output can only be produced in the order of one index at a time even though WAMPUM automatically updates up to 7 active indexes as you add and modify entries in the file. The LEAD INDEX is always the FIRST index displayed at the bottom of the WAMPUM Main System Menu. If you want to retrieve records in some order other than what the current LEAD INDEX would provide, then you can change the LEAD INDEX. Except in FoxBASE+, press the ALT-I hot key. Similarly, all output from WAMPUM including REPORTS, LABELS, and FORM LETTERS is produced in the order of the LEAD INDEX. If you want the output ordered differently, then you must change the LEAD INDEX before generating the report, labels, or form letters. The only exception is using the W - WAMPUM PreFormat option. To change the LEAD INDEX in any version, choose the S - Select Utilities option from the Main System Menu by typing an S or highlighting the option and pressing the <ENTER> key. 90 Enter any selection criteria desired then press <ENTER> to move to the field which asks Change Lead Index. Change the value of the field from False to True by typing either a T or Y. Assuming you have more than one index in use, a list of available indexes then will be displayed. Just enter the number of the one which you want to designate as the LEAD INDEX. 3.9.6 Setting Browse Mode ON WAMPUM implements dBASE III's powerful BROWSE command in a slightly different way. BROWSE Mode may be turned ON by specifying T or Y to the prompt in the Select Utilities screen. Except in FoxBASE+ versions, you also may press the ALT-B hot key from the Main Menu. In all versions, WAMPUM uses a two-step process for EDITing, DISPLAYing, DELETing, and UNDELETing records. The user first will be prompted for the key field value to find. Then, instead of the usual data entry display, the user first will be presented with a table of the first twenty records in key order beginning with the first matching key value. WAMPUM displays as many fields from the data base for each record as will fit on a single line of the screen. Within this display, the user can move UP and DOWN through the records with the UP and DOWN cursor keys. The user can request the next twenty records beginning with the last record currently displayed by pressing the <PgDn> key. Browse also permits the user to move UP a single record by pressing <PgUp>. If the record is found for which you are searching, then simply highlight that option and press the <ENTER> key. This then triggers the usual WAMPUM data entry screen. If no record is found for which you desire to move to the full data entry screen, then two choices are available. Pressing <ESC> will ABORT the BROWSE session and return you to the Main System Menu. BROWSE mode is particularly useful in situations in which there may be multiple entries with a similar key value, i.e. a number of entries with LASTNAME of Smith. BROWSE permits you to examine the partial contents of 20 records at a time in order to identify the exact record with which to work. Note that you cannot actually change any data while in this BROWSE mode. You must move to the actual data entry screen to do this. NOTE: FoxBASE+ version users may run the special BROWSER program from the & menu option for full BROWSE functionality by typing DO BROWSER. If a record has been marked for deletion, that entry will show an asterisk (*) as the first character of the line. Otherwise, the first character position is always blank. 91 Once the full data entry mode has been triggered by pressing the <ENTER> key, the user still has the ability to move through the data base with either <PgDn> or <PgUp>. At this juncture, it is necessary to return to the Main System Menu before the BROWSE mode is reinitiated. 3.9.7 Listing the File Structure Particularly in developing reports, labels, form letters, and edit checks, it is helpful to have a listing of the structure of the data base file in use. The last option on the Select Utilities screen permits a user to request this listing. If the prompt is answered with Y or T, then WAMPUM will ask whether you want the listing printed as opposed to displayed. Typing T or Y at the Printed? option will provide a printed listing. Pressing <ESC> will abort the listing entirely. Pressing <PgDn> or <ENTER> will display the file structure on the screen. 3.10 R - REPORTS Generation The R - Reports option allows you to run existing dBASE III report formats and create new ones. Creation of new reports is covered in the Developer's Section. Before selecting the Reports option, first pick the S - Select Utilities option to enter Record Selection Criteria and to specify the Lead Index for report output. When you select the Reports option, a listing of report forms in the default directory will be displayed. You then are prompted to enter the name of the report form you wish to run. In FoxBASE+ versions, type in the file name EXACTLY as it appears in the directory listing. Do NOT include the .FRM file extension. In other versions, highlight the report form to be executed and press <ENTER>. There also is a field which allows you to specify the PRINTER FONT to be used if the report is to be printed. If a report is to be printed on regular 8-1/2 x 11 inch paper using 10 pitch type, then NO font number needs to be entered. If your printer supports smaller fonts thereby enabling production of wider reports or reports turned sideways, enter a number corresponding to the font desired. See the # - Printer Config section of the Developer's Section of this User's Guide for more information. Once you have entered a font or pressed the <ENTER> key, the Printer Selection Screen will appear. Answer the 92 prompts. Or see the Printer Selection Screen section for more information. 3.11 L - LABELS Production The L - Labels option allows you to run existing dBASE label formats and create new ones. Creation of new labels is covered in the Developer's section of this User's Guide. Before selecting the Labels option, first pick the Select Utilities option to enter Record Selection Criteria and to specify the Lead Index for label output. When you select the Labels option, a listing of label forms in the default directory will be displayed. In FoxBASE+ versions, you then are prompted to enter the name of the label form you wish to run. Type in the file name EXACTLY as it appears in the directory listing. Do NOT include the .LBL file extension. In other versions, simply highlight the label form to be executed and press <ENTER>. There also is a field which allows you to specify the PRINTER FONT to be used if the labels are to be printed. If the labels are to be printed using standard 10 pitch type, then NO font number needs to be entered. If you will be producing labels on a laser printer, then FONT7 should be selected. See the # - Printer Config section of the Developer's Section for more information. Once you have entered a font or pressed the <ENTER> key, answer the prompts on the Printer Selection Screen. See the Printer Selection Screen section of this User's Guide for more information on these options. 3.12 T - FORM LETTER Generation The T - Form Letters option allows you to run existing WAMPUM form letters and create new ones. Creation of new form letters is covered in the Developer's Section. Before selecting the Form Letters option, first choose the Select Utilities option. Enter Record Selection Criteria and specify the Lead Index for form letter output. The one exception to this is if you wish to generate a form letter using an indexed key to print a form for a single record. In this case, make certain that no Record Selection Criteria are in effect. Then select the T - Form Letters option. After selecting a form letter file as outlined below, you will be prompted to enter the key value to find using the primary index then in effect. 93 When you select the Form Letters option, a listing of form letter files in the default directory will be displayed. In FoxBASE+ versions, a form letter file is a standard .DBF file except that its file name begins with T-. You then are prompted to enter the name of the form letter form you wish to run. Type in the file name EXACTLY as it appears in the directory listing. Do NOT include the .DBF file extension. In other versions, form letters are standard ASCII documents with a file name extension of .TXT. Highlight the form desired and press <ENTER>. Answer the prompts on the Printer Selection Screen and <PgDn>. Or see the Printer Selection Screen section of this User's Guide for more information on these options. 3.13 W - WAMPUM Preformatted Output The W - WAMPUM Preformatted Output option allows you to run up to 80 predefined Reports, Labels, and Form Letters each with predefined selection criteria, sort order, and even a related file for table lookup if desired. This is WAMPUM's most unique feature and is NOT available in other dBASE- compatible products. Before this option is available, the WAMPUM master file must be created and appropriate entries must be made for the pre-defined output desired. This is covered in the Developer's section of this User's Guide. Then all that is necessary to run WAMPUM Preformatted Output is to select the W - WAMPUM PreFormat option from the Main System Menu. A two-column listing of reports, labels, and form letters available for automatic production then will be displayed. Following the description of each item will be a single letter (R, L, or T) indicating whether the output is a Report, Label, or Form Letter. In FoxBASE+ versions, there also is an & option signifying that the choice is a FoxBASE- compatible program. Mark the desired output you wish to produce with a T or Y in the logical field provided to indicate which should be run. At the bottom of the screen a range of dates is specified for output which requires these. The default range of dates is the beginning and ending of the current month unless today's date is less than the 6th of the month. In this case, the default is the beginning and ending dates of last month. Most folks produce monthly reports for a prior month at the beginning of the next month so WAMPUM saves you a little typing. 94 The range of dates can be changed by you to any dates desired although the first date should always be less than or equal to the second date. The range of dates are automa- tically used for any preformatted reports, labels, or form letters in which the developer wanted the end-user to have the flexibility to select the time period for the report at the time it was produced. Once you have entered your choices, the Printer Selection Screen appears. Answer the prompts and <PgDn>. See the next section for more information on these options. 3.14 Printer Selection Screen 3.14.1 Printed Output Whenever you run a Report, Label, Form Letter, or WAMPUM Preformatted Output, you will see the Printer Selection Screen which lets you choose whether to PRINT or DISPLAY the information. If you want the OUTPUT printed, type a T or Y. 3.14.2 Printer Font Selection In some WAMPUM versions, font selection also is made on the Printer Selection Screen. Choose the font number corresponding to the type style desired for the output you have chosen. This will be a number between 0 and 9. With preformatted output, this option does not apply. 3.14.3 Output All Records If record selection criteria are in effect, you also will be asked whether you want to override those criteria and OUTPUT information on ALL records in the data base. If you DO want to OVERRIDE the record selection criteria in effect, then change the default entry to T or Y. 3.14.4 Output Records Marked for Deletion You also will be asked whether to output information on records marked for DELETION. The default is No. If you want DELETED records included, change the entry to T or Y. 95 3.15 On-Line HELP The best way to learn WAMPUM is to read this User's Guide cover to cover. Many won't do that so WAMPUM provides some of what is contained in the User's Guide in HELP screens keyed to where you are in the program. To access the HELP screens, press the F1 function key at any time. Depending upon where you are in WAMPUM, a screen of HELP will be displayed. Simply press the <ENTER> key to return to where you were. Every choice from the WAMPUM Main System Menu has an intermediate screen which gives you a chance to change your mind. In FoxBASE+ versions, it is on this second screen after picking any option that the most detailed HELP is available. In other versions, simply highlight the choice on the Main Menu and press F1 for HELP. 3.16 Credits The following are trademarks or registered trademarks of the respective companies: WAMPUM and MenuMaker Ward Mundy Clipper Nantucket Corporation FoxBASE and FoxBASE+ Fox Software, Inc. dBASE, dBASE III, dBASE III Plus Ashton-Tate dBASE IV Ashton-Tate LOTUS, 1-2-3, and Symphony LOTUS Development Co. IBM, IBM PC, and IBM PC-AT IBM Corporation HP LaserJet, Plus, and LaserJet II Hewlett-Packard 96